International Postal Code API

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. 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-postal-code.api.smarty.com/lookup?auth-id=123&auth-token=abc

URL components:

• Scheme: https
  (Required; non-secure http requests are not supported.)
• Hostname: international-postal-code.api.smarty.com
• Path: /lookup
• 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:

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

HTTP GET

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 locality, administrative_area, postal_code, and country fields:

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

	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 non-encoded pound sign (#), like in an apartment number (# 409), is a common mistake we see. This character, when properly encoded in a URL, becomes %23. When not encoded, this character functions as the fragment identifier, which our API servers ignore.

HTTP request: Headers

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

Host	The Host request header field specifies the internet host and port number of the resource being requested	Host: international-postal-code.api.smarty.com

Input fields

Each query submitted must have non-blank values for one of the following field combinations to be processed. Any combination of parameters may be submitted to narrow the search criterion.

• country + locality
• country + administrative_area
• country + postal_code

A maximum of 1,000 results will be returned for each query. Since there is no paging capability to return more than the maximum, you will need to refine your search to return fewer results.

Name	Type	Max characters	Description
input_id	string	36	A unique identifier generated by you for this address for use within your application; this field will be copied into the output. (e.g., 123456)
country	string	64	(required) This must be entered with every address. Country Name or ISO classification (ISO-3, ISO-2, or ISO-N). Address validation will fail if this is missing. (e.g., Brazil, BRA, BR, or 076)
locality	string	64	The city name (e.g., Paris).
administrative_area	string	32	The state or province name or abbreviation (e.g., Alberta or AB)
postal_code	string	16	The postal code (e.g., T4B 5M7). You may submit a postal code prefix to widen your search. (e.g., T4B 5)
license	string	64	The license or licenses (comma-separated) to use for this lookup. Valid values can be found in the account dashboard under the appropriate subscription. If multiple licenses are specified, they are considered in left-to-right order.

HTTP response: Status codes and results

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

Status code	Response and explanation
401	Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials. Additionally, a unique situation can trigger a 401 error when embedded keys are used server-side from a cloud environment or VPN.
402	Payment required: There is no active subscription for the account associated with the credentials submitted with the request.
400	Bad request (malformed payload): Inputs from the request could not be interpreted.
422	Unprocessable entity: A GET request lacked required fields.
429	Too many requests: Too many requests with exactly the same input values were submitted within too short a period. This status code conveys that the input was not processed in order to prevent runaway charges caused by such conditions as a misbehaving (infinite) loop that's sending the same record over and over to the API. You're welcome.
429 (again)	Too many requests: When using public "embedded key" authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded key in question.
504	Gateway timeout: Our own upstream data provider did not respond in a timely fashion, and the request failed. A serious, yet rare occurrence indeed.
200	OK (success!): A JSON object containing zero or more matches for the input provided with the request. If the input is not valid or no matches are found, the object will contain an empty array {"results":[]}.

Full example: Query by locality and administrative area

Request

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

	locality=Sao+Paulo&
	administrative_area=SP&
	country=Brazil'

Response

Only the first three results are shown. The API may return up to 1,000 results.

{
	"results": [
		{
			"administrative_area": "SP",
			"country_iso_3": "BRA",
			"locality": "São Paulo",
			"postal_code": "02245-000"
		},
		{
			"administrative_area": "SP",
			"country_iso_3": "BRA",
			"locality": "São Paulo",
			"postal_code": "02418-140"
		},
		{
			"administrative_area": "SP",
			"country_iso_3": "BRA",
			"locality": "São Paulo",
			"postal_code": "02478-000"
		}
		... results truncated ...
	]
}

Full example: Query by postal code

Request

curl -v 'https://international-postal-code.api.smarty.com/lookup?
	input_id=1234&
	auth-id=YOUR+AUTH-ID+HERE&
	auth-token=YOUR+AUTH-TOKEN+HERE&

	postal_code=02516-040&
	country=Brazil

Response

{
	"results": [
		{
			"input_id": "1234",
			"administrative_area": "SP",
			"country_iso_3": "BRA",
			"locality": "São Paulo",
			"dependent_locality": "Casa Verde",
			"postal_code": "02516-040"
		}
	]
}

Output fields

A maximum of 1,000 results will be returned for each query. Since there is no paging capability to return more than the maximum, you will need to refine your search to return fewer results.

Field name	Type	Definition
input_id	varchar(16)	A unique identifier generated by you for this address for use within your application. The output will be identical to the value you provided in the request input_id.
administrative_area	varchar(64)	The most common administrative division within a country (e.g., province in Canada)
super_administrative_area	varchar(64)	The largest administrative division within a country (e.g., region in France)
sub_administrative_area	varchar(64)	The smallest administrative division within a country (e.g., county in Germany)
locality	varchar(64)	Within a country, this is the most common population center. (e.g., city in Chile)
dependent_locality	varchar(64)	If there is additional information about the locality, it will be here. (e.g., neighborhood in Turkey)
dependent_locality_name	varchar(64)	If the dependent_locality has a name, you'll find it here. (E.g., the dependent_locality "Dong Cheng Qu" is named "Dong Cheng.")
double_dependent_locality	varchar(64)	If there is additional information about the dependent_locality, you'll find it here. (e.g., village in the United Kingdom)
postal_code	varchar(64)	The complete postal code for the delivery point (e.g., V6G1V9 in Canada)
postal_code_extra	varchar(64)	Secondary postal code information (e.g., 3425 in the United States)

Supported countries

For a list of supported countries, see our international address validation documentation.

SSL/TLS information

Use modern security software and cipher suites.