Address vs geocode

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 as UNCONFIRMED_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 to PREMISE, indicating that the given address is granular down to a building.

• Notice that the geocodeGranularity field is OTHER, indicating that the geocode returned refers to a large area, and indeed, looking at the placeTypes field you can see that the geocode is of type locality, 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"
}