International Postal Code API - reference

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:

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’s no paging capability to return more than the maximum number of results, you will need to refine your search to return fewer results.

Transliteration isn’t available in this API. All results will be returned using the Latin character set.

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.

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"
		}
	]
}

Full example: Query by postal code with language parameter (JPN only)

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=891-3607&
	country=JPN&
    language=native

Response

[
  {
    "input_id": "1234",
    "administrative_area": "鹿児島県",
    "country_iso_3": "JPN",
    "locality": "熊毛郡",
    "dependent_locality": "中種子町",
    "thoroughfare": "田島",
    "postal_code": "８９１－３６０７"
  }
]

Output fields

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

Transliteration isn’t available in this API. All results will be returned using the Latin character set.

Supported countries

For a list of supported countries, see our international Address Autocomplete API documentation.

SSL/TLS information

Use modern security software and cipher suites.