international-postal-code-api.yaml

openapi: 3.1.0
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.'