The response
of an Address Validation API call
contains a unique address
and a unique geocode
.
The address
represents the API's best understanding of the address in the input,
and the geocode
represents the API's best guess at the location represented by
the address
.
This difference is somewhat subtle so it's worth illustrating with an example.
Request
The following request body to an Address Validation API call refers to a street and street number that do not exist.
{
"address": {
"regionCode": "US",
"administrativeArea": "California",
"locality": "Mountain View",
"addressLines": ["123 Fake St"]
}
}
Response
The Address Validation API call returns the response shown below. There are several things to note in the response:
The
address
contains a street number component, "123", and a street component, "Fake St," both marked asUNCONFIRMED_BUT_PLAUSIBLE
. This means that the API was not able to confirm the existence of this street and street number.However, even though this street and the number do not exist in our data, the API was able to recognize that the semantic meaning of this part of the input was a street and a street number, and for that reason it sets the
inputGranularity
toPREMISE
, indicating that the given address is granular down to a building.Notice that the
geocodeGranularity
field isOTHER
, indicating that the geocode returned refers to a large area, and indeed, looking at theplaceTypes
field you can see that the geocode is of typelocality
, which happened because the API was not able to locate the street number or the street.
{
"result": {
"verdict": {
"inputGranularity": "PREMISE",
"validationGranularity": "OTHER",
"geocodeGranularity": "OTHER",
"hasUnconfirmedComponents": true
},
"address": {
"formattedAddress": "123 Fake St, Mountain View, CA, USA",
"postalAddress": {
"regionCode": "US",
"languageCode": "en",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"123 Fake St"
]
},
"addressComponents": [
{
"componentName": {
"text": "123",
"languageCode": "en"
},
"componentType": "street_number",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
"componentName": {
"text": "Fake St",
"languageCode": "en"
},
"componentType": "route",
"confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
},
{
"componentName": {
"text": "Mountain View",
"languageCode": "en"
},
"componentType": "locality",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "CA",
"languageCode": "en"
},
"componentType": "administrative_area_level_1",
"confirmationLevel": "CONFIRMED"
},
{
"componentName": {
"text": "USA",
"languageCode": "en"
},
"componentType": "country",
"confirmationLevel": "CONFIRMED"
}
],
"missingComponentTypes": [
"postal_code"
],
"unconfirmedComponentTypes": [
"street_number",
"route"
]
},
"geocode": {
"location": {
"latitude": 37.3860517,
"longitude": -122.0838511
},
"plusCode": {
"globalCode": "849V9WP8+CF"
},
"bounds": {
"low": {
"latitude": 37.3567832,
"longitude": -122.1178619
},
"high": {
"latitude": 37.469887,
"longitude": -122.0446721
}
},
"featureSizeMeters": 9943.329,
"placeId": "ChIJiQHsW0m3j4ARm69rRkrUF3w",
"placeTypes": [
"locality",
"political"
]
},
"uspsData": {
"standardizedAddress": {
"firstAddressLine": "123 FAKE ST",
"cityStateZipAddressLine": "MOUNTAIN VIEW",
"city": "MOUNTAIN VIEW",
"state": "CA"
},
"dpvFootnote": "A1",
"dpvCmra": "N",
"postOfficeCity": "MOUNTAIN VIEW",
"postOfficeState": "CA"
}
},
"responseId": "20cfe06a-9d39-4da6-80e0-eef852e9ea8d"
}