Smarty Lookup API

openapi: 3.2.0
info:
  title: Smarty Lookup API
  license:
    url: https://www.smarty.com/legal/terms-of-service
    name: Smarty License
  termsOfService: https://smartystreets.com/legal/terms-of-service
  version: '1.0'
  description: 'Operations tagged Lookup across 2 of this provider''s published API definitions: smarty-international-address-autocomplete-api-openapi.yml, smarty-us-zipcode-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://international-autocomplete.api.smarty.com
- url: https://us-zipcode.api.smarty.com
tags:
- name: Lookup
paths:
  /v2/lookup:
    get:
      summary: Get Autocomplete Suggestions
      tags:
      - Lookup
      security:
      - auth-id: []
        auth-token: []
      - embedded-key: []
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          description: 'Bad Request (Malformed Payload): The request was malformed in some way and could not be parsed.'
        '401':
          description: 'Unauthorized: The embedded key was provided incorrectly or did not match any existing, active embedded keys. Or the host in the referer header did not match a host assigned to your embedded key.'
        '402':
          description: 'Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.'
        '422':
          description: 'Unprocessable Entity (Unsuitable parameters): Returns errors describing what needs to be corrected.'
        '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. You can avoid this error by adding your IP address as an authorized host for the embedded key in question.'
      operationId: get-lookup
      parameters:
      - $ref: '#/components/parameters/Host'
      - $ref: '#/components/parameters/Referer'
      - $ref: '#/components/parameters/country'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/max_results'
      - $ref: '#/components/parameters/max_group_results'
      - $ref: '#/components/parameters/geolocation'
      - $ref: '#/components/parameters/include_only_locality'
      - $ref: '#/components/parameters/include_only_postal_code'
    servers:
    - url: https://international-autocomplete.api.smarty.com
  /v2/lookup/{addressId}:
    get:
      summary: Get Autocomplete Suggestions
      tags:
      - Lookup
      security:
      - auth-id: []
        auth-token: []
      - embedded-key: []
      responses:
        '200':
          $ref: '#/components/responses/detailed_200'
        '400':
          description: 'Bad Request (Malformed Payload): The request was malformed in some way and could not be parsed.'
        '401':
          description: 'Unauthorized: The embedded key was provided incorrectly or did not match any existing, active embedded keys. Or the host in the referer header did not match a host assigned to your embedded key.'
        '402':
          description: 'Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.'
        '422':
          description: 'Unprocessable Entity (Unsuitable parameters): Returns errors describing what needs to be corrected.'
        '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. You can avoid this error by adding your IP address as an authorized host for the embedded key in question.'
      operationId: get-lookup-id
      parameters:
      - $ref: '#/components/parameters/Host'
      - $ref: '#/components/parameters/Referer'
      - $ref: '#/components/parameters/country'
      - $ref: '#/components/parameters/address_id'
      - $ref: '#/components/parameters/max_results'
      - $ref: '#/components/parameters/max_group_results'
      - $ref: '#/components/parameters/geolocation'
      - $ref: '#/components/parameters/include_only_locality'
      - $ref: '#/components/parameters/include_only_postal_code'
    servers:
    - url: https://international-autocomplete.api.smarty.com
  /lookup:
    get:
      tags:
      - Lookup
      summary: Search for a single ZIP 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 the city, state, and zipcode fields:

        ```bash

        curl -v ''https://us-zipcode.api.smarty.com/lookup?

        auth-id=YOUR+AUTH-ID+HERE&

        auth-token=YOUR+AUTH-TOKEN+HERE&

        city=mountain+view&

        state=CA&

        zipcode=94035''

        ```

        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/city'
      - $ref: '#/components/parameters/state'
      - $ref: '#/components/parameters/zipcode'
      - $ref: '#/components/parameters/input_id'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Host_2'
      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/Root'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '413':
          $ref: '#/components/responses/413'
        '429':
          $ref: '#/components/responses/429'
      security:
      - auth_id: []
        auth_token: []
      - website_key: []
    post:
      tags:
      - Lookup
      summary: Search for a batch of ZIPCodes
      operationId: lookup-post
      description: 'HTTP POST: Multiple Inputs\n\nA POST request allows a larger volume of data (MAX: 100 inputs or 16K per request) to be sent in the HTTP request body. In this case, the data should be encoded as a JSON array where each element in the array is a JSON object with field names identical to those in the field listing below. Here''s a sample request with three inputs being sent:

        ```

        curl -v ''https://us-zipcode.api.smarty.com/lookup?

        auth-id=YOUR+AUTH-ID+HERE&

        auth-token=YOUR+AUTH-TOKEN+HERE''

        -H "Content-Type: application/json; charset=utf-8"

        --data-binary ''

        [

        {

        "city":"North Pole",

        "state":"AK"

        },

        {

        "zipcode":"12345"

        },

        {

        "city":"cupertino",

        "state":"CA",

        "zipcode":"95014"

        }

        ]''

        ```

        Note: When POSTing JSON, always make sure to add a Content-Type of application/json; charset=utf-8."'
      requestBody:
        description: Data should be encoded as a `JSON` array where each element in the array is a `JSON` object with field names identical to those in the provided examples.
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/LookupManyArray'
        required: true
      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; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Root'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '413':
          $ref: '#/components/responses/413'
        '429':
          $ref: '#/components/responses/429'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Host_2'
      security:
      - auth_id: []
        auth_token: []
      - website_key: []
    servers:
    - url: https://us-zipcode.api.smarty.com
components:
  responses:
    detailed_200:
      description: 'OK (success!): The response body is a JSON object with a candidates array containing candidates based on the supplied input parameters.'
      content:
        application/json:
          schema:
            type: object
            properties:
              candidates:
                type: array
                items:
                  $ref: '#/components/schemas/detailed_candidate'
    '200':
      description: 'OK (success!): The response body is a JSON object with a candidates array containing candidates based on the supplied input parameters.'
      content:
        application/json:
          schema:
            type: object
            properties:
              candidates:
                type: array
                items:
                  $ref: '#/components/schemas/candidate'
    '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.'
    '400':
      description: 'Bad Request (Malformed Payload): The request body of a POST request contained no lookups or contained malformed JSON.'
    '413':
      description: 'Request Entity Too Large: The maximum size for a request body to this API is 16K (16,384 bytes).'
    '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.'
  parameters:
    country:
      name: country
      in: query
      required: true
      schema:
        type: string
      description: The ISO3 Alpha-3 country code where the desired address is located. Only uppercase values are allowed. See supported country codes (https://www.smarty.com/docs/cloud/international-address-autocomplete-api#supported-country-codes). Maximum length is 3 bytes.
    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. Note: Most HTTP clients such as the browser, or programming language HTTP libraries will add this header automatically. Ex: Host: us-autocomplete-pro.api.smarty.com'
    include_only_locality:
      name: include_only_locality
      in: query
      required: false
      schema:
        type: string
      description: 'Limit the results to only the locality provided. A locality is a significant population center (i.e. city, town, or village). When this parameter is used, include_only_postal_code cannot be used. Separate multiple values with a comma. Example: Paris,Versailles'
    max_group_results:
      name: max_group_results
      in: query
      required: false
      schema:
        type: integer
      description: Maximum number of address suggestions to return when expanding address groups with an Address ID; range [1, 100].
    include_only_postal_code:
      name: include_only_postal_code
      in: query
      required: false
      schema:
        type: string
      description: 'Limit the results to only the postal codes provided. When this parameter is used, include_only_locality cannot be used. Separate multiple values with a comma. Example: 29200,29201'
    geolocation:
      name: geolocation
      in: query
      required: false
      schema:
        type: string
      description: "Bias (prefer) results based on the location of the sender's IP address (IPv4 only). Valid value: on \n Supported countries: CAN, AUS, DEU. If the request to the API goes through a proxy, you will need to set an X-Forwarded-For header specifying the desired IP address for the request."
    address_id:
      name: addressId
      in: path
      required: true
      schema:
        type: string
      description: The Address ID is used to get further information about a particular result. This value will be supplied by a previous call to the API. This parameter should not be supplied when the search query parameter is used.
    search:
      name: search
      in: query
      required: true
      schema:
        type: string
      description: The part of the address that has already been typed. Maximum character count is 32 characters. Required when address ID is not specified in the URL.
    Referer:
      name: Referer
      in: header
      schema:
        type: string
      description: 'The Referer is required when an embedded key is used for authentication. Its value is in the form of a URL, where the host component must match a host value assigned to your embedded key. Note: Some HTTP clients such as a browser or programming language HTTP libraries will add this header automatically. However some interfaces such as cURL do not, so you may need to add it manually. Ex: Referer: https://mycoolwebsite.com'
      required: false
    max_results:
      name: max_results
      in: query
      required: false
      schema:
        type: integer
      description: 'Maximum number of address suggestions to return; range [1, 10]. Default: 5'
    Host_2:
      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: us-zipcode.api.smarty.com'
    Content-Type:
      name: Content-Type
      in: header
      required: true
      schema:
        type: string
      description: 'The purpose of the Content-Type field is to describe the data contained in the body fully enough that the receiving user agent can pick an appropriate agent or mechanism to present the data to the user, or otherwise deal with the data in an appropriate manner. EX: Content-Type: application/json; charset=utf-8'
    input_id:
      name: input_id
      in: query
      example: 867-5309
      description: '**Input ID** *Example: 867-5309* A unique identifier for this address used in your application; this field will be copied to the output'
      schema:
        type: string
    zipcode:
      name: zipcode
      in: query
      description: '**Zip code** *Example: 84604* The ZIP Code.'
      schema:
        type: string
    state:
      name: state
      in: query
      description: '**State** *Example: UT* State name or two-letter abbreviation. Must be paired with ''city'' if no ZIPCode is provided.'
      schema:
        type: string
    city:
      name: city
      in: query
      description: The city name
      schema:
        type: string
  schemas:
    candidate:
      title: candidate
      type: object
      properties:
        entries:
          type: integer
        address_text:
          type: string
        address_id:
          type: string
      examples:
      - entries: 12
        address_text: 123 Main St Winnipeg, MB, R3C
        address_id: PD4DPC8DOjE4AzI9Uig2MTE2Lzo4UjI+NjEgLCtSTk1M
    detailed_candidate:
      title: detailed_candidate
      type: object
      properties:
        street:
          type: string
        locality:
          type: string
        administrative_area:
          type: string
        administrative_area_short:
          type: string
        administrative_area_long:
          type: string
        postal_code:
          type: string
        country_iso3:
          type: string
      examples:
      - street: 1-123 Main St
        locality: Fredericton
        administrative_area: NB
        administrative_area_short: NB
        administrative_area_long: New Brunswick
        postal_code: E3A 1C7
        country_iso3: CAN
    ZIPCodes:
      title: ZIPCodes
      type: object
      properties:
        zipcode:
          type: string
          example: '84604'
          description: The 5 digit ZIP code
        zipcode_type:
          type: string
          example: S
          description: 'The type of ZIP Code. Possible values:

            S - Standard (regular ZIP Code)

            M - Military (APO/FPO military ZIP Code. Also includes DPO - Diplomatic addresses)

            P - P.O. Box (serves only post-office boxes)

            U - Unique (belongs primarily to a firm)'
        default_city:
          type: string
          example: Provo
          description: A string containing the default city name for this ZIP Code
        county_fips:
          type: string
          example: '49049'
          description: The county FIPS Code
        county_name:
          type: string
          example: Utah
          description: 'The name of the county in which the ZIP Code is located


            Note: The county name listed here pertains to the 5-digit ZIP Code, not necessarily the city.'
        state_abbreviation:
          type: string
          example: UT
          description: The official, two-letter state abbreviation
        state:
          type: string
          example: Utah
          description: The state name
        latitude:
          type: number
          example: 40.26763
          description: The approximate latitude geo-coordinate
        longitude:
          type: number
          example: -111.65763
          description: The approximate longitude geo-coordinate
        precision:
          type: string
          example: Zip5
          description: "Indicates the precision of the latitude and longitude values. \n\nNone — Coordinates not known. Reasons could include: address is invalid, military address (APO or FPO), lat/lon coordinates not available.\nZip5 — Accurate to a 5-digit ZIP Code level (least precise)\nZip6 — Accurate to a 6-digit ZIP Code level\nZip7 — Accurate to a 7-digit ZIP Code level\nZip8 — Accurate to an 8-digit ZIP Code level\nZip9 — Accurate to a 9-digit ZIP Code level (most precise but NOT rooftop level)"
        alternate_counties:
          type: array
          description: 'The county FIPS codes, county names, state abbreviations, and states, that share the same ZIP Code. Note: The county names listed here pertain to the 5-digit ZIP Code, not necessarily the city.'
          items:
            $ref: '#/components/schemas/AlternateCounties'
    Root:
      title: Successful response
      type: object
      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.'
      properties:
        input_index:
          type: integer
        input_id:
          type: string
          description: A unique identifier for this address used in your application; this field will be copied into the output.
        city_states:
          type: array
          description: A list of cities and their states that match the input
          items:
            $ref: '#/components/schemas/CityStates'
        zipcodes:
          type: array
          description: A list of ZIP Codes that match the input
          items:
            $ref: '#/components/schemas/ZIPCodes'
        status:
          type: string
          description: For a lookup with no matches, status classifies the kind of failure and always comes with a reason
        reason:
          type: string
          description: "For a lookup with no matches, reason explains why the lookup failed\n\nblank\tBlank lookup (you must provide a ZIP Code and/or City/State combination).\ninvalid_state\tInvalid State name or abbreviation.\ninvalid_city\tInvalid City for the given State.\ninvalid_zipcode\tInvalid ZIP Code.\nconflict\tConflicting ZIP Code/City/State information."
    LookupManyArray:
      type: string
    CityStates:
      title: CityStates
      type: object
      properties:
        city:
          type: string
          example: Provo
          description: The name of a city
        state_abbreviation:
          type: string
          example: UT
          description: The official, two-letter state abbreviation
        state:
          type: string
          example: Utah
          description: The state name
        mailable_city:
          type: boolean
          description: A boolean value indicating whether or not the city name is an approved USPS mailing name
    AlternateCounties:
      title: AlternateCounties
      type: object
      properties:
        county_fips:
          type: string
          example: '49051'
          description: The county FIPS Code
        county_name:
          type: string
          example: Utah
          description: 'The name of the county in which the ZIP Code is located


            Note: The county name listed here pertains to the 5-digit ZIP Code, not necessarily the city.'
        state_abbreviation:
          type: string
          example: UT
          description: The official, two-letter state abbreviation
        state:
          type: string
          example: Utah
          description: The state name
      description: 'The county FIPS codes, county names, state abbreviations, and states, that share the same ZIP Code. Note: The county names listed here pertain to the 5-digit ZIP Code, not necessarily the city.

        '
  securitySchemes:
    auth-id:
      type: apiKey
      name: auth-id
      in: query
    auth-token:
      type: apiKey
      name: auth-token
      in: query
    embedded-key:
      type: apiKey
      name: key
      in: query
    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
x-refined-from:
- smarty-international-address-autocomplete-api-openapi.yml
- smarty-us-zipcode-api-openapi.yml