When using the Address Validation API, you can request that a validation response also return the address converted into English. Use this feature when your system needs to provide address information in English-based Latin characters when receiving an address originating in a non-English language. For example:
- Your company might fulfill shipping requests from all over the world and use English and English-based Latin characters to standardize all addresses.
- Your business might handle shipments to and from a country that uses a different language than the language of the provided address.
How to return an address in English
To request an address validation with included English-equivalent components, add the following to the validation request body:
"languageOptions": { "returnEnglishLatinAddress": "true" }
The following example requests English-based components while verifying the address to the Prado Museum:
curl -X POST -d '{
"address": {
"region_code" : "ES",
"address_lines": ["C. de Ruiz de Alarcón, 23, 28014 Madrid, Spain"],
},
"languageOptions": {returnEnglishLatinAddress: true}
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-Api-Key: API_KEY' \
'https://addressvalidation.googleapis.com/v1:validateAddress'
The response returns the English address in the englishLatinAddress field. See
Address conversion example below for details. Each
component of the returned local language address is converted into English as
best as possible. The converted address is not reusable as an input to the API.
The englishLatinAddress field uses the same
Address
proto as the address field uses, with the following exceptions:
- No
ConfirmationLevelfield - No
unconfirmedComponentTypesfield
How address conversion works
The Address Validation API applies English conversion to each component of
the address. This means that the administrative_area, the locality and other
components of the address are treated individually. See
AddressComponent
in the reference documentation for a list of the address components.
The following diagram illustrates what English conversion would look like for the address Calle Dueñas, 5, 41003 Sevilla, España.
For each component evaluated for English conversion, the service uses the process described in the following sections.
Uses fully-translated English where possible
Some address components might have a fully-translated version available for use.
For example, the Spanish country of España would be translated to Spain. In
that case, the service uses the English version. This is typically the case for
larger address components such as country and administrative_area_level_1.
Uses latinization of the local language if English is not available
Latinization means that the local language is converted to the Latin script using transcription.
- If the local language of the address uses a Latin character
set, and no English equivalent exists for the address component, the service
replaces characters from the local language that are not English-based.
For example,
Calle DueñasbecomesCalle Duenas, where ñ is substituted with n. - If the local language of the address does not use a Latin-based
character set, and no English equivalent exists for the address component,
the service uses a latinized version of the local language, if available.
For example, a Japanese conversion returns the romanization of Japanese.
Any non-English, non-Latin characters are replaced with English-based
Latin characters. For example: ３丁目 becomes 3-chome.
- Note that Japanese is not yet enabled for the preview
- If a latinized version of the language is not available, the components are returned in the local language.
Substitutes Latin characters not in English
Any Latin characters not in English are replaced with their English-character equivalent. For example, each of the following characters would be replaced by the character "o": ð, ò, ó, ô, õ, ö, ø, ō, ŏ, ő, ơ, ṍ, ṏ, ṑ, ṓ, ọ, ỏ, ố, ồ, ổ, ỗ, ộ, ớ, ờ, ở, ỡ, and ợ. For example:
Calle de Ruiz de Alarcón becomes Calle de Ruiz de Alarcon
Address conversion example
The following example shows a validation response from a request for the Palacio
de las Dueñas in Spain, with the englishLatinAddress in bold. This request
used the field returnEnglishLatinAddress in the languageOptions parameter in
the input.
"result": { "verdict": { "inputGranularity": "PREMISE", "validationGranularity": "PREMISE", "geocodeGranularity": "PREMISE", "addressComplete": true, "hasInferredComponents": true }, "address": { "formattedAddress": "Calle Dueñas, 5, 41003 Sevilla, España", "postalAddress": { "regionCode": "ES", "languageCode": "es", "postalCode": "41003", "administrativeArea": "Sevilla", "locality": "Sevilla", "addressLines": [ "C. Dueñas, 5" ] }, "addressComponents": [ { "componentName": { "text": "Calle Dueñas", "languageCode": "es" }, "componentType": "route", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "5", "languageCode": "es" }, "componentType": "street_number", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "41003" }, "componentType": "postal_code", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "Sevilla", "languageCode": "es" }, "componentType": "locality", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "España", "languageCode": "es" }, "componentType": "country", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "Sevilla", "languageCode": "es" }, "componentType": "administrative_area_level_2", "confirmationLevel": "CONFIRMED", "inferred": true } ] }, "geocode": { "location": { "latitude": 37.394849, "longitude": -5.9893604 }, "plusCode": { "globalCode": "8C9P92V6+W7" }, "bounds": { "low": { "latitude": 37.3948098, "longitude": -5.9894249 }, "high": { "latitude": 37.3948882, "longitude": -5.9893025 } }, "featureSizeMeters": 7.174035, "placeId": "ChIJzRDYbgRsEg0RDDgHlF80UoI", "placeTypes": [ "premise" ] }, "metadata": { "business": true, "residential": false }, "englishLatinAddress": { "formattedAddress": "Calle Duenas, 5, 41003 Seville, Spain", "postalAddress": { "regionCode": "ES", "languageCode": "en", "postalCode": "41003", "administrativeArea": "Seville", "locality": "Seville", "addressLines": [ "C. Duenas, 5" ] }, "addressComponents": [ { "componentName": { "text": "Calle Duenas", "languageCode": "es" }, "componentType": "route", }, { "componentName": { "text": "5", "languageCode": "es" }, "componentType": "street_number", }, { "componentName": { "text": "41003" }, "componentType": "postal_code", }, { "componentName": { "text": "Seville", "languageCode": "en" }, "componentType": "locality", }, { "componentName": { "text": "Spain", "languageCode": "en" }, "componentType": "country", }, { "componentName": { "text": "Seville", "languageCode": "en" }, "componentType": "administrative_area_level_2", "inferred": true } ] } }, "responseId": "e874d263-7d0d-413f-9213-119a784765ed"
Support options for Preview releases
Although Google does not provide support for Preview versions, features, or functionality of the Services, we consider requests at these developmental stages on a case-by-case basis.
Use these recommendations for pre-GA versions:
Pre-GA features are not covered by the Google Maps Platform SLA.
Use fallback mechanisms, especially if you are using a pre-GA feature in a production environment. Some examples of fallback situations are: quota exceeded, unexpected response codes and latency, or unexpected responses when compared to the existing behavior.
You can use the issue tracker to request new features or suggest modifications to existing features. Be sure to include the following in your request:
Describe the specific feature or behavior you would like to see added, as well as the reasons you think it's important.
If possible, include specific details about your use case and the new opportunities the feature would allow for.
For this feedback or any other questions on features, send an email to the Address Validation Hotline: address-validation-hotline@google.com.