International Postal Code API
Validates and looks up postal codes for international locations, returning associated city, region, and geographic metadata for a given country and postal code combination.
OpenAPI Specification
openapi: 3.0.1
info:
title: International-Postal-Code-API
description: |
Utilize the SmartyStreets RESTful API to search for a Country and locality OR administrative area OR postal code and access more relevant information than you could possibly need.
termsOfService: 'https://smartystreets.com/legal/terms-of-service'
contact:
url: 'https://www.smarty.com/contact/support'
email: [email protected]
name: Smarty Support
license:
url: 'https://www.smarty.com/legal/terms-of-service'
name: Smarty License
version: 4.1.3
servers:
- url: 'https://international-postal-code.api.smarty.com'
externalDocs:
description: Extensive documentation for the International-Postal-Code-API
url: 'https://smartystreets.com/docs/cloud/international-postal-code-api'
paths:
/lookup:
get:
tags:
- lookup
summary: Search country and locality/administrative area/postal code
operationId: lookup-get
description: |
To send one (and only one) input to the API, simply encode the field names from the table below along with their corresponding 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:
```bash
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 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.
parameters:
- $ref: '#/components/parameters/Host'
- $ref: '#/components/parameters/input_id'
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/locality'
- $ref: '#/components/parameters/administrative_area'
- $ref: '#/components/parameters/postal_code'
- $ref: '#/components/parameters/license'
responses:
'200':
description: 'OK(success!), The response body will be a JSON array containing zero or more matches for the input provided with the request. The structure of the response is the same for both GET and POST requests.'
content:
application/json:
schema:
$ref: '#/components/schemas/Results'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'402':
$ref: '#/components/responses/402'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
security:
- auth_id: [ ]
auth_token: [ ]
- website_key: [ ]
tags:
- name: lookup
description: Search country and locality/administrative area/postal code
components:
parameters:
Host:
name: Host
in: header
required: true
schema:
type: string
description: 'The Host request header field specifies the internet host and port number of the resource being requested. EX: Host: international-postal-code.api.smarty.com'
input_id:
name: input_id
in: query
example: 8675309
description: 'A unique identifier for this address used in your application; this field will be copied to the output'
schema:
type: string
country:
name: country
in: query
required: true
description: 'This must be entered with every address. Country Name or ISO classification (ISO-3, ISO-2, ISO-N). Address validation will fail if this is missing. (e.g. Brazil, BRA, BR, or 076)'
schema:
type: string
locality:
name: locality
in: query
example: 'Paris'
description: 'The city name'
schema:
type: string
administrative_area:
name: administrative_area
in: query
description: 'The state or province name or abbreviation. (e.g. Alberta or AB)'
schema:
type: string
postal_code:
name: postal_code
in: query
description: 'The postal code (e.g. T4B 5M7). You may submit a postal code preefix to widen your search. (e.g. T4B 5)'
schema:
type: string
license:
name: license
in: query
description: '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.'
schema:
type: string
schemas:
Results:
title: Successful response
type: object
description: 'OK (success!): The response body will be a JSON array containing 0 to 1000 items for the input provided with the request. Since there is no paging capability to return more than the maximum, you will need to refine your search to return fewer results. Transliteration is not available in this API. All results will be returned using the Latin character set.'
properties:
input_id:
type: string
description: '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:
type: string
description: 'The most common administrative division within a country (ex. province in Canada)'
super_administrative_area:
type: string
description: 'The largest administrative division within a country (ex. region in France)'
sub_administrative_area:
type: string
description: 'The smallest administrative division within a country (ex. county in Germany)'
locality:
type: string
description: 'Within a country, this is the most common population center (ex. city in Chile)'
dependent_locality:
type: string
description: 'If there is additional information about the locality, it will be here (ex. neighborhood in Turkey)'
dependent_locality_name:
type: string
description: "If the dependent_locality has a name, you'll find it here. (ex. the dependent_locality 'Dong Cheng Qu' is named 'Dong Cheng')"
double_dependent_locality:
type: string
description: "If there is additional information about the dependent_locality, you'll find it here. (ex. village in the United Kingdom)"
postal_code:
type: string
description: 'The complete postal code for the delivery point (ex. V6G1V9 in Canada)'
postal_code_extra:
type: string
description: 'Secondary postal code information (ex. 3425 in the United States)'
country_iso_3:
type: string
description: 'The ISO 3166-1 alpha-3 country code'
securitySchemes:
auth_id:
type: apiKey
name: auth-id
in: query
auth_token:
type: apiKey
name: auth-token
in: query
website_key:
type: apiKey
name: key
in: query
responses:
'400':
description: 'Bad Request (Malformed Payload): The request body of a POST request contained no lookups or contained malformed JSON.'
'401':
description: 'Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.'
'402':
description: 'Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.'
'422':
description: 'Unprocessable Entity: A GET request lacked required fields.'
'429':
description: |
'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.'
'OR'
'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.'
'504':
description: 'Gateway Timeout: Our own upstream data provider did not repond in a timely fashion, and the request failed. A serious, yet rare occurrence indeed.'