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: support@smarty.com 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.'