International Street Address API - reference

This page describes how to verify an international address using Smarty's international address verification API. (View current pricing.)

Contents

1. HTTP request
   1. URL composition
   2. Request methods
   3. Headers
   4. Input fields
2. HTTP response
   1. Status codes and results
   2. Output field definitions
   3. How to interpret the raw data output
3. Supplementary material
   1. Full examples
   2. Supported countries
   3. SSL/TLS information
   4. Try the API

HTTP request: URL composition

Proper URL construction is required for all API requests. Here is an example URL:

https://international-street.api.smarty.com/verify?auth-id=123&auth-token=abc

URL components:

• Scheme: https
  (Required; non-secure http requests are not supported.)
• Hostname: international-street.api.smarty.com
• Path: /verify
• Query string: ?auth-id=123&auth-token=abc
  Note #1: Additional query string parameters are required; consult the next section.

For additional information, please read our article about URL components.

HTTP request: Supported methods/verbs

HTTP requests can be categorized according to their HTTP method. Most HTTP requests are defined using the GET method. We call these "get requests." Other common methods are PUT, POST, and DELETE.

The following methods are supported by this API:

• OPTIONS (for "pre-flight" cross domain requests)
• GET (for sending a single request with query parameters)

To send one (and only one) address to our API, simply encode the input field names from the table below along with the corresponding input values as query string parameters in the URL of your request. Here's an example that uses the address1, address2, locality, administrative_area, postal_code, and country fields:

curl -v 'https://international-street.api.smarty.com/verify?
	auth-id=YOUR+AUTH-ID+HERE&
	auth-token=YOUR+AUTH-TOKEN+HERE&

	address1=Rua+Padre+Antonio+D%27Angelo+121&
	address2=Casa+Verde&
	locality=Sao+Paulo&
	administrative_area=SP&
	postal_code=02516-040&
	country=Brazil'

Please note that all query string parameter values must be url-encoded (spaces become + or %20, for example) to ensure that the data is transferred correctly. A common mistake we see is a non-encoded pound sign (#) like in an apartment number (# 409). This character, when properly encoded in a URL, becomes %23. When not encoded this character functions as the fragment identifier, which is ignored by our API servers.

HTTP request: Headers

You must include the following required HTTP headers in all requests:

Input fields

The following input fields are required:

• country
• freeform OR address1

If freeform is used, it should contain the entire address minus the country.

Example
Country: Brazil
Freeform: Rua Padre Antonio D'Angelo 121 Sao Paulo 02516-040 SP

If address1 is used, address1 can contain the entire address, however, the ideal combination of input fields, which has the best chance of finding a valid address match, is as follows:

country + address1 + locality + administrative_area + postal_code

In this case, the address1 field should contain the thoroughfare (street) name and the premise number.

Example
Country: Brazil
Address1: Rua Padre Antonio D'Angelo 121
Locality: Sao Paulo 02516-040
Administrative Area: SP
Postal Code: 02516-040

HTTP response: Status codes and results

Responses will have a status header with a numeric value. This value is what you should check for when writing code to parse the response. The only response body that should be read and parsed is a 200 response.

How to interpret the raw data output

This part of the document explains how to interpret the “Analysis” section of our International Street Address API output. You will need to be familiar with the explanations of the Analysis output fields found in the International Address Verification documentation here.

If you feel confident in those explanations and definitions, continue reading below.

Steps to interpreting the output

1. Check the "verification_status" output field, which tells you whether the address is verified or not

   When we say an address is "verified," we mean that we found a match between the address you or your user input and a standardized version of the address contained in an authoritative dataset for the particular country.

   We return a “verification_status” of [Verified] if the address is verified to the precision of DeliveryPoint or Premise, meaning that the address has been identified to a specific, valid delivery point range.

   We return a “verification_status” of [Partial] if the address is verified to the precision level of Thoroughfare (street) or worse. For some countries whose maximum precision level is less than DeliveryPoint or Premise, this may be the best verification status you may receive.

   If the “verification_status” is [Ambiguous], that does NOT necessarily indicate that the address is invalid; it simply means that because the input address wasn’t quite complete enough to find a single address match, multiple addresses are provided in the output. In that case, it will be important to check the "address_precision" value for EACH of the address candidates. (See the next step.)

2. If you need to know the precision level to which the address is verified, check the "address_precision" output field.

   When we say precision, we’re referring to having the level of accuracy defined. If we can’t give you premise-accurate precision, Smarty’s tools are intuitive enough to say what level of accuracy was actually achieved when matching the address against the authority dataset.

3. If you submitted an address with a subunit (like a suite or apartment number), check the following output field to see if the subunit is valid.

   Within the "changes" portion of the API output, check the output field titled "sub_building." If that output field contains [Verified], the subunit is verified. This means that the subunit isn’t solely identified because of its position in the address, but is an actual subunit that is known to exist at the address.

4. Check the entire "changes" section of the output to make sure you’re comfortable with what was changed between the input address and the output address.

   In other words, the "changes" output fields tell you if the address in the output is actually the one you’re looking for.

   For example, if the "changes" section tells you that the premise (building number) had a change (which would be rare), then the output address is probably NOT the same address as the one you or your user input.

   In contrast, a change in the “postal_code” field is probably acceptable and only indicates that we corrected the postal code.

Full example: Verify only (no geocodes)

Request

curl -v 'https://international-street.api.smarty.com/verify?
	auth-id=YOUR+AUTH-ID+HERE&
	auth-token=YOUR+AUTH-TOKEN+HERE&

	address1=Rua+Padre+Antonio+D%27Angelo+121&
	address2=Casa+Verde&
	locality=Sao+Paulo&
	administrative_area=SP&
	postal_code=02516-040&
	country=Brazil'

Response

Every response is a JSON array containing zero or more address matches for your input. Only non-blank fields will be returned.

[
	{
		"address1":"Rua Padre Antônio D'ângelo 121",
		"address2":"Casa Verde",
		"address3":"02516-040 São Paulo SP",
		"components":{
			"administrative_area":"SP",
			"dependent_locality":"Casa Verde",
			"country_iso_3":"BRA",
			"locality":"São Paulo",
			"postal_code":"02516-040",
			"postal_code_short":"02516-040",
			"premise":"121",
			"premise_number":"121",
			"thoroughfare":"Rua Padre Antônio D'ângelo",
			"thoroughfare_name":"Padre Antonio D'angelo",
			"thoroughfare_type":"Rua"
		},
		"metadata":{

		},
		"analysis":{
			"verification_status":"Verified",
			"address_precision":"Premise"
		}
	}
]

Full example: Verify + geocode

Request

curl -v 'https://international-street.api.smarty.com/verify?
	auth-id=YOUR+AUTH-ID+HERE&
	auth-token=YOUR+AUTH-TOKEN+HERE&

	address1=Rua+Padre+Antonio+D%27Angelo+121&
	address2=Casa+Verde&
	locality=Sao+Paulo&
	administrative_area=SP&
	postal_code=02516-040&
	country=Brazil&
	geocode=true'

Response

Every response is a JSON array containing zero or more address matches for your input.

[
	{
		"address1":"Rua Padre Antônio D'ângelo 121",
		"address2":"Casa Verde",
		"address3":"02516-040 São Paulo SP",
		"components":{
			"administrative_area":"SP",
			"dependent_locality":"Casa Verde",
			"country_iso_3":"BRA",
			"locality":"São Paulo",
			"postal_code":"02516-040",
			"postal_code_short":"02516-040",
			"premise":"121",
			"premise_number":"121",
			"thoroughfare":"Rua Padre Antônio D'ângelo",
			"thoroughfare_name":"Padre Antonio D'angelo",
			"thoroughfare_type":"Rua"
		},
		"metadata":{
			"latitude":-23.50948,
			"longitude":-46.66073,
			"geocode_precision":"Premise"
		},
		"analysis":{
			"verification_status":"Verified",
			"address_precision":"Premise"
		}
	}
]

Output fields

NOTE: Any returned fields that are not defined within this document should be considered experimental and may be changed or discontinued at any time without notice.

Root | Components | Metadata | Analysis | Changes

Root

Components

Metadata

Analysis

Changes

Possible values

Each value in this object (and any subordinate objects) will have a type of varchar(64) and will either be blank or contain one of the following values:

Supported countries

The below countries are supported and available in our international address validation. Notice that the verification and geocode accuracy levels are different for each country. That means that addresses in Nicaragua, for example, can only be verified to the locality or city because that is the best data available for that country.

Note: Smarty recommends that any USA address be processed through our us-street-address-api, as the response will contain more useful metadata.

SSL/TLS information

Use modern security software and cipher suites.