us-zipcode-api.yml

openapi: 3.0.1
info:
  title: "US-ZIPCode-API"
  description: |
    Utilize the SmartyStreets RESTful API to search for a ZIPCode or City/State combo and access more relevant information than you could possibly need. 
  termsOfService: "https://smartystreets.com/legal/terms-of-service"
  contact:
    name: "the Smarty Pit-Crew"
    email: "support@smartystreets.com"
  version: 4.1.3
  
servers:
- url: https://us-zipcode.api.smartystreets.com/
  
paths:
  /lookup:
    get:
      tags:
      - lookup
      summary: Search for a single ZIPCode
      description: |
        Provide either a 'city'/'state' combo or just a 'zipcode' and an optional 'input_id'
      parameters:
        - $ref: '#/components/parameters/city'
        - $ref: '#/components/parameters/state'
        - $ref: '#/components/parameters/zipcode'
        - $ref: '#/components/parameters/input_id'
      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/200'
        401:
          description: Unauthorized
          content:
            text/plain:
              schema:
                example: The credentials were provided incorrectly or did not match any existing, active credentials.
                type: string
        402:
          description: Payment Required
          content:
            text/plain:
              schema:
                example: There is no active subscription for the account associated with the credentials submitted with the request.
                type: string
        413:
          description: Request Entity Too Large
          content:
            text/plain:
              schema:
                example: The maximum size for a request body to this API is 16K (16,384 bytes).
                type: string
        400:
          description: Bad Request (Malformed Payload)
          content:
            text/plain:
              schema:
                example: The request body of a POST requeset contained no lookups or contained malformed JSON.
                type: string
        429:
          description: Too Many Requests
          content:
            text/plain:
              schema:
                example: When using public "website key" authentication, we restrict the number of requests coming from a given source over too short of a time. If you use "website key" authentication, you can avoid this error by adding your IP address as an authorized host for the website key in question.
                type: string
    post:
      tags:
      - lookup
      summary: Search for a batch of ZIPCodes
      description: Search for a larger volume of data (up to 100 inputs or 16K per request)
      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: successful operation
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/200'
        403:
          description: Invalid API key, or other reason why access is forbidden.

security: 
- auth_id: []
  auth_token: []
- website_key: []

tags:
- name: lookup
  description: Search City/States or ZIPCodes
  
externalDocs:
  description: "Extensive documentation for the US-ZIPCode-API"
  url: https://smartystreets.com/docs/cloud/us-zipcode-api
  
components:
  parameters:
    city:
      name: city
      in: query
      description: "**City** *Example: Provo* Must be paired with 'state' if no ZIPCode is provided."
      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
    zipcode:
      name: zipcode
      in: query
      description: "**Zip code** *Example: 84604* The ZIP Code."
      schema:
        type: string
    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
        
  schemas:
    200:
      title: Successful response
      type: object
      properties:
        input_index:
          type: integer
        input_id:
          type: string
        city_states:
          type: array
          items:
            $ref: '#/components/schemas/CityStates'
        zipcodes:
          type: array
          items:
            $ref: '#/components/schemas/ZIPCodes'
    CityStates:
      title: CityStates
      type: object
      properties:
        city:
          type: string
          example: Provo
        state_abbreviation:
          type: string
          example: 'UT'
        state:
          type: string
          example: 'Utah'
        mailable_city:
          type: boolean
    ZIPCodes:
      title: ZIPCodes
      type: object
      properties:
        zipcode:
          type: string
          example: '84604'
        zipcode_type:
          type: string
          example: 'S'
        default_city:
          type: string
          example: 'Provo'
        county_fips:
          type: string
          example: '49049'
        county_name:
          type: string
          example: 'Utah'
        state_abbreviation:
          type: string
          example: 'UT'
        state:
          type: string
          example: 'Utah'
        latitude:
          type: number
          example: 40.26763
        longitude:
          type: number
          example: -111.65763
        precision:
          type: string
          example: 'Zip5'
        alternate_counties:
          type: array
          items:
            $ref: '#/components/schemas/AlternateCounties'
    AlternateCounties:
      title: AlternateCounties
      type: object
      properties:
        county_fips:
          type: string
          example: '49051'
        county_name:
          type: string
          example: 'Wasatch'
        state_abbreviation:
          type: string
          example: 'UT'
        state:
          type: string
          example: 'Utah'
    LookupManyArray:
      type: string
      example:
        - {"city": "North Pole", "state": "AK"}
        - {"zipcode": "12345"}
        - {"city": "cupertino", "state": "california", "zipcode": "95014"}
  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