Using the APIs
Addresses
{
"object": "address.resolution_result",
"created": 1764892800,
"input": {
"address": "1600 Amphitheatre Parkway, Mountain View, CA"
},
"normalized": "1600 Amphitheatre Parkway, Mountain View, CA 94043, United States",
"components": {
"street_number": "1600",
"thoroughfare": {
"name": "Amphitheatre Parkway"
},
"localities": [
{
"name": "Mountain View",
"type": "city"
}
],
"admin_areas": [
{
"name": "California",
"code": "CA",
"type": "state",
"level": 1
}
],
"region": "California",
"region_code": "CA",
"postal_code": "94043",
"country": "United States",
"country_code": "US",
"address_lines": [
"1600 Amphitheatre Parkway",
"Mountain View, CA 94043",
"United States"
],
"canonical_form": "1600 AMPHITHEATRE PARKWAY, MOUNTAIN VIEW, CA 94043, US",
"coordinates": {
"lat": 37.4224764,
"lng": -122.0842499
},
"metadata": {
"confidence": 0.95,
"address_type": "commercial",
"deliverability": "deliverable",
"timezone": "America/Los_Angeles"
}
}
}Resolve an Address
Normalize and optionally validate an address
{
"object": "address.resolution_result",
"created": 1764892800,
"input": {
"address": "1600 Amphitheatre Parkway, Mountain View, CA"
},
"normalized": "1600 Amphitheatre Parkway, Mountain View, CA 94043, United States",
"components": {
"street_number": "1600",
"thoroughfare": {
"name": "Amphitheatre Parkway"
},
"localities": [
{
"name": "Mountain View",
"type": "city"
}
],
"admin_areas": [
{
"name": "California",
"code": "CA",
"type": "state",
"level": 1
}
],
"region": "California",
"region_code": "CA",
"postal_code": "94043",
"country": "United States",
"country_code": "US",
"address_lines": [
"1600 Amphitheatre Parkway",
"Mountain View, CA 94043",
"United States"
],
"canonical_form": "1600 AMPHITHEATRE PARKWAY, MOUNTAIN VIEW, CA 94043, US",
"coordinates": {
"lat": 37.4224764,
"lng": -122.0842499
},
"metadata": {
"confidence": 0.95,
"address_type": "commercial",
"deliverability": "deliverable",
"timezone": "America/Los_Angeles"
}
}
}validate: true in options to include deliverability and consistency checks in the response.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
API version in YYYY-MM-DD format.
Provide on POST requests to make them idempotent for safe retries.
Body
- Option 1
- Option 2
Request to resolve an address into normalized, structured format.
Free-form address text.
A structured representation of a postal address designed for global coverage. Compatible with the Universal Postal Union (UPU) standards, CLDR address formats, and major geocoding providers. Supports addresses from all countries including complex East Asian, Middle Eastern, and rural addressing systems.
Show child attributes
Show child attributes
Person name or primary recipient.
Company or institution name.
Attention line (e.g., c/o, Attn:).
Named building, complex, or estate (e.g., Empire State Building, 小区名称).
Block, tower, wing, or staircase identifier within a building.
Specific entrance identifier or code.
Floor number or level (e.g., 5F, Ground Floor, 3階).
Door number or identifier.
Apartment, suite, or room number.
Street or road information with directional and type components.
Show child attributes
Show child attributes
Street name without type or direction (e.g., Main, 中山路).
Street type (e.g., St, Rd, Ave, Boulevard, 大道, Straße).
Directional prefix (e.g., N, South, 东).
Directional suffix (e.g., NE, West, 西).
Block, sector, quarter, or chome (丁目) designation.
Primary street number or building number (e.g., 123, 1-2-3 for Japanese addresses).
East Asian block number (e.g., Japanese chome/banchi 丁目/番地, Korean block 번지).
Lot or parcel number within a block.
Reference landmark for landmark-based addressing (common in developing countries).
Special delivery instructions or access codes.
Ordered smallest-to-largest locality hierarchy (e.g., neighborhood → city → post_town). At least one locality is typically present for valid addresses.
1Show child attributes
Show child attributes
Locality name in specified language.
Type of locality.
neighborhood, dependent_locality, village, town, city, post_town, municipality, district, subdistrict, quarter, unknown BCP-47 language code of the locality name.
Ordered smallest-to-largest administrative areas (e.g., county → state → region). Supports hierarchical structures with up to 5 levels for countries with complex administrative divisions.
1Show child attributes
Show child attributes
Administrative area name.
Type of administrative division.
county, department, province, state, prefecture, region, oblast, canton, parish, emirate, district, governorate, unknown Official code (e.g., ISO 3166-2 subdivision code, postal abbreviation).
Hierarchical level (1=smallest, 5=largest).
1 <= x <= 5Top-level administrative area (convenience field, typically duplicates largest admin_area).
Top-level administrative area code (e.g., CA for California, SP for São Paulo).
Postal or ZIP code. Format varies by country.
Extended postal code suffix (e.g., +4 in US ZIP+4).
Additional sorting/routing codes (e.g., CEDEX in France, DPS codes).
Post office box number.
Type of postal box (e.g., PO Box, Private Bag, Locked Bag).
Rural route or highway contract delivery information.
Full country name.
ISO 3166-1 alpha-2 country code (uppercase).
2Primary language of this address (BCP-47 format, e.g., en-US, zh-Hans-CN).
Native-script representation for display, printing, and labels. Essential for addresses in non-Latin scripts (Arabic, CJK, Cyrillic, etc.).
Canonical formatted display lines in postal order for the target country. Generated by the resolver based on country-specific formatting rules.
Fully normalized single-line postal form for equality testing and deduplication. Standardized format regardless of input variations.
Metadata about the resolution process and data sources.
Show child attributes
Show child attributes
Normalizer confidence score (0–1).
Original data source/provider reference.
Classification of the address type.
residential, commercial, po_box, military, educational, government, unknown Deliverability assessment of the address.
deliverable, undeliverable, unknown IANA timezone identifier (e.g., America/Los_Angeles).
Response
OK
Result of address resolution. Fields present depend on options.
"address.resolution_result"Epoch seconds.
Show child attributes
Show child attributes
A structured representation of a postal address designed for global coverage. Compatible with the Universal Postal Union (UPU) standards, CLDR address formats, and major geocoding providers. Supports addresses from all countries including complex East Asian, Middle Eastern, and rural addressing systems.
Show child attributes
Show child attributes
Person name or primary recipient.
Company or institution name.
Attention line (e.g., c/o, Attn:).
Named building, complex, or estate (e.g., Empire State Building, 小区名称).
Block, tower, wing, or staircase identifier within a building.
Specific entrance identifier or code.
Floor number or level (e.g., 5F, Ground Floor, 3階).
Door number or identifier.
Apartment, suite, or room number.
Street or road information with directional and type components.
Show child attributes
Show child attributes
Street name without type or direction (e.g., Main, 中山路).
Street type (e.g., St, Rd, Ave, Boulevard, 大道, Straße).
Directional prefix (e.g., N, South, 东).
Directional suffix (e.g., NE, West, 西).
Block, sector, quarter, or chome (丁目) designation.
Primary street number or building number (e.g., 123, 1-2-3 for Japanese addresses).
East Asian block number (e.g., Japanese chome/banchi 丁目/番地, Korean block 번지).
Lot or parcel number within a block.
Reference landmark for landmark-based addressing (common in developing countries).
Special delivery instructions or access codes.
Ordered smallest-to-largest locality hierarchy (e.g., neighborhood → city → post_town). At least one locality is typically present for valid addresses.
1Show child attributes
Show child attributes
Locality name in specified language.
Type of locality.
neighborhood, dependent_locality, village, town, city, post_town, municipality, district, subdistrict, quarter, unknown BCP-47 language code of the locality name.
Ordered smallest-to-largest administrative areas (e.g., county → state → region). Supports hierarchical structures with up to 5 levels for countries with complex administrative divisions.
1Show child attributes
Show child attributes
Administrative area name.
Type of administrative division.
county, department, province, state, prefecture, region, oblast, canton, parish, emirate, district, governorate, unknown Official code (e.g., ISO 3166-2 subdivision code, postal abbreviation).
Hierarchical level (1=smallest, 5=largest).
1 <= x <= 5Top-level administrative area (convenience field, typically duplicates largest admin_area).
Top-level administrative area code (e.g., CA for California, SP for São Paulo).
Postal or ZIP code. Format varies by country.
Extended postal code suffix (e.g., +4 in US ZIP+4).
Additional sorting/routing codes (e.g., CEDEX in France, DPS codes).
Post office box number.
Type of postal box (e.g., PO Box, Private Bag, Locked Bag).
Rural route or highway contract delivery information.
Show child attributes
Show child attributes
Full country name.
ISO 3166-1 alpha-2 country code (uppercase).
2Primary language of this address (BCP-47 format, e.g., en-US, zh-Hans-CN).
Native-script representation for display, printing, and labels. Essential for addresses in non-Latin scripts (Arabic, CJK, Cyrillic, etc.).
Canonical formatted display lines in postal order for the target country. Generated by the resolver based on country-specific formatting rules.
Fully normalized single-line postal form for equality testing and deduplication. Standardized format regardless of input variations.
Metadata about the resolution process and data sources.
Show child attributes
Show child attributes
Normalizer confidence score (0–1).
Original data source/provider reference.
Classification of the address type.
residential, commercial, po_box, military, educational, government, unknown Deliverability assessment of the address.
deliverable, undeliverable, unknown IANA timezone identifier (e.g., America/Los_Angeles).
Canonical single-line address in requested format (e.g., postal).
A structured representation of a postal address designed for global coverage. Compatible with the Universal Postal Union (UPU) standards, CLDR address formats, and major geocoding providers. Supports addresses from all countries including complex East Asian, Middle Eastern, and rural addressing systems.
Show child attributes
Show child attributes
Person name or primary recipient.
Company or institution name.
Attention line (e.g., c/o, Attn:).
Named building, complex, or estate (e.g., Empire State Building, 小区名称).
Block, tower, wing, or staircase identifier within a building.
Specific entrance identifier or code.
Floor number or level (e.g., 5F, Ground Floor, 3階).
Door number or identifier.
Apartment, suite, or room number.
Street or road information with directional and type components.
Show child attributes
Show child attributes
Street name without type or direction (e.g., Main, 中山路).
Street type (e.g., St, Rd, Ave, Boulevard, 大道, Straße).
Directional prefix (e.g., N, South, 东).
Directional suffix (e.g., NE, West, 西).
Block, sector, quarter, or chome (丁目) designation.
Primary street number or building number (e.g., 123, 1-2-3 for Japanese addresses).
East Asian block number (e.g., Japanese chome/banchi 丁目/番地, Korean block 번지).
Lot or parcel number within a block.
Reference landmark for landmark-based addressing (common in developing countries).
Special delivery instructions or access codes.
Ordered smallest-to-largest locality hierarchy (e.g., neighborhood → city → post_town). At least one locality is typically present for valid addresses.
1Show child attributes
Show child attributes
Locality name in specified language.
Type of locality.
neighborhood, dependent_locality, village, town, city, post_town, municipality, district, subdistrict, quarter, unknown BCP-47 language code of the locality name.
Ordered smallest-to-largest administrative areas (e.g., county → state → region). Supports hierarchical structures with up to 5 levels for countries with complex administrative divisions.
1Show child attributes
Show child attributes
Administrative area name.
Type of administrative division.
county, department, province, state, prefecture, region, oblast, canton, parish, emirate, district, governorate, unknown Official code (e.g., ISO 3166-2 subdivision code, postal abbreviation).
Hierarchical level (1=smallest, 5=largest).
1 <= x <= 5Top-level administrative area (convenience field, typically duplicates largest admin_area).
Top-level administrative area code (e.g., CA for California, SP for São Paulo).
Postal or ZIP code. Format varies by country.
Extended postal code suffix (e.g., +4 in US ZIP+4).
Additional sorting/routing codes (e.g., CEDEX in France, DPS codes).
Post office box number.
Type of postal box (e.g., PO Box, Private Bag, Locked Bag).
Rural route or highway contract delivery information.
Full country name.
ISO 3166-1 alpha-2 country code (uppercase).
2Primary language of this address (BCP-47 format, e.g., en-US, zh-Hans-CN).
Native-script representation for display, printing, and labels. Essential for addresses in non-Latin scripts (Arabic, CJK, Cyrillic, etc.).
Canonical formatted display lines in postal order for the target country. Generated by the resolver based on country-specific formatting rules.
Fully normalized single-line postal form for equality testing and deduplication. Standardized format regardless of input variations.
Metadata about the resolution process and data sources.
Show child attributes
Show child attributes
Normalizer confidence score (0–1).
Original data source/provider reference.
Classification of the address type.
residential, commercial, po_box, military, educational, government, unknown Deliverability assessment of the address.
deliverable, undeliverable, unknown IANA timezone identifier (e.g., America/Los_Angeles).
Present only if the result is persisted.