openapi: 3.0.3
info:
  title: ZipCodeAPI
  version: "1.0.0"
  description: |
    REST API for ZIP and postal code lookups, distance calculations, radius queries,
    city-state matching, and more. API key is required in the URL path.

servers:
  - url: https://www.zipcodeapi.com/

paths:

  /rest/{apiKey}/distance.json/{zip1}/{zip2}/{unit}:
    get:
      summary: Distance between two ZIP codes
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/zip1'
        - $ref: '#/components/parameters/zip2'
        - $ref: '#/components/parameters/unit'
      responses:
        '200': { $ref: '#/components/responses/DistanceResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/v2/CA/{apiKey}/distance.json/{caPostal1}/{caPostal2}/{unit}:
    get:
      summary: Distance between two Canadian postal codes
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/caPostal1'
        - $ref: '#/components/parameters/caPostal2'
        - $ref: '#/components/parameters/unit'
      responses:
        '200': { $ref: '#/components/responses/DistanceResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/{apiKey}/multi-distance.json/{zip}/{zipsCsv}/{unit}:
    get:
      summary: Distance between one ZIP code and multiple other ZIP codes
      description: Each zip code provided will count as a separate request. For example, if you send 5 zip codes, you will be charged for 5 requests. Any zip code not found will not be included in the response.
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/zip'
        - $ref: '#/components/parameters/zipsCsv'
        - $ref: '#/components/parameters/unit'
      responses:
        '200': { $ref: '#/components/responses/MultiDistanceResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/{apiKey}/radius.json/{zip}/{distance}/{unit}:
    get:
      summary: ZIP codes within a radius
      description: Find all US ZIP codes within a given radius of a ZIP code. The radius is capped at 500 miles unless the minimal option is used or you have the unlimited subscription.
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/zip'
        - $ref: '#/components/parameters/distance'
        - $ref: '#/components/parameters/unit'
        - in: query
          name: minimal
          schema: { type: boolean }
          description: If true, returns only ZIP codes, but allows a radius larger than 500 miles.
      responses:
        '200':
          description: Radius response (minimal or full)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/responses/MinimalRadiusResponse'
                  - $ref: '#/components/responses/RadiusResponse'
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/v2/CA/{apiKey}/radius.json/{zip}/{distance}/{unit}:
    get:
      summary: Canadian postal codes within a radius
      description: Find all Canadian postal codes within a given radius of a postal code. The radius is capped at 805 km and the number of responses is capped at 250 postal codes unless the minimal or simple option is used or you have the unlimited subscription.
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/zip'
        - $ref: '#/components/parameters/distance'
        - $ref: '#/components/parameters/unit'
        - in: query
          name: minimal
          schema: { type: boolean }
          description: If true, returns only postal codes, but allows a radius larger than 805 km.
        - in: query
          name: simple
          schema: { type: boolean }
          description: If true, returns only postal codes, but allows a radius larger than 805 km.
      responses:
        '200':
          description: Radius response (minimal, simple, or full)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/responses/MinimalCanadianRadiusResponse'
                  - $ref: '#/components/responses/SimpleCanadianRadiusResponse'
                  - $ref: '#/components/responses/CanadianRadiusResponse'
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/{apiKey}/info.json/{zip}/{latLongUnit}:
    get:
      summary: Get info for a ZIP code
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/zip'
        - $ref: '#/components/parameters/latLongUnit'
      responses:
        '200': { $ref: '#/components/responses/InfoResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/{apiKey}/multi-info.json/{zipsCsv}/{latLongUnit}:
    get:
      summary: Get info for multiple ZIP codes
      description: A max of 100 ZIP codes is allowed. Each zip code provided will count as a separate request. For example, if you send 5 zip codes, you will be charged for 5 requests.
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/zipsCsv'
        - $ref: '#/components/parameters/latLongUnit'
      responses:
        '200': { $ref: '#/components/responses/MultiInfoResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/v2/CA/{apiKey}/info.json/{caPostal1}/{latLongUnit}:
    get:
      summary: Get info for a Canadian postal code
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/caPostal1'
        - $ref: '#/components/parameters/latLongUnit'
      responses:
        '200': { $ref: '#/components/responses/CanadianInfoResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/{apiKey}/city-zips.json/{city}/{state}:
    get:
      summary: Get ZIP codes for a city
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - name: city
          in: path
          required: true
          schema: { type: string }
        - name: state
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/CityZipsResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/v2/CA/{apiKey}/city-postal-codes.json/{city}/{province}:
    get:
      summary: Get postal codes for a city
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - name: city
          in: path
          required: true
          schema: { type: string }
        - name: province
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/CanadianCityPostalCodesResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/{apiKey}/match-close.json/{zipsCsv}/{distance}/{unit}:
    get:
      summary: Find close ZIP codes
      description: Send a list of up to 100 zip codes and return all pairs where the distance between the zip codes is less than a given distance.
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - $ref: '#/components/parameters/zipsCsv'
        - $ref: '#/components/parameters/distance'
        - $ref: '#/components/parameters/unit'
      responses:
        '200': { $ref: '#/components/responses/MatchCloseResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

  /rest/{apiKey}/state-zips.json/{state}:
    get:
      summary: Get zip codes for a state
      description: Get all zip codes in a US state. This API is charged as multiple requests. Every 10 zip codes returned are charged as 1 request. For example, if the state you select returns 200 zip codes, you will be charged for 20 requests.
      parameters:
        - $ref: '#/components/parameters/apiKey'
        - name: state
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { $ref: '#/components/responses/StateZipCodesResponse' }
        '401': { $ref: '#/components/responses/Error401' }
        '404': { $ref: '#/components/responses/Error404' }
        '429': { $ref: '#/components/responses/Error429' }

components:
  parameters:
    apiKey:
      name: apiKey
      in: path
      required: true
      schema: { type: string }
      description: Your API key
    zip:
      name: zip
      in: path
      required: true
      schema:
        type: string
        pattern: '^\d{5}$'
      example: "08057"
    zip1:
      name: zip1
      in: path
      required: true
      schema:
        type: string
        pattern: '^\d{5}$'
      example: "08057"
    zip2:
      name: zip2
      in: path
      required: true
      schema:
        type: string
        pattern: '^\d{5}$'
        example: "12345"
    zipsCsv:
      name: zipsCsv
      in: path
      required: true
      schema:
        type: string
        pattern: '^\d{5}(,\d{5})*$'
      description: Comma-separated ZIPs to filter
      example: "08057,12345"
    caPostal1:
      name: caPostal1
      in: path
      required: true
      schema:
        type: string
        pattern: '^([A-Za-z]\d){3}$'
    caPostal2:
      name: caPostal2
      in: path
      required: true
      schema:
        type: string
        pattern: '^([A-Za-z]\d){3}$'
    distance:
      name: distance
      in: path
      required: true
      schema:
        type: number
    unit:
      name: unit
      in: path
      required: true
      schema:
        type: string
        enum: [mile, km]
    latLongUnit:
      name: latLongUnit
      in: path
      required: true
      schema:
        type: string
        enum: [degrees, radians]

  schemas:
    ZipCodeInfo:
      type: object
      properties:
        zip_code: { type: string }
        city: { type: string }
        state: { type: string }
        lat: { type: number }
        lng: { type: number }
        timezone:
          $ref: '#/components/schemas/TimeZone'
        acceptable_city_names:
          type: array
          items:
            type: object
            properties:
              city:
                type: string
                example: "Moorestown"
              state:
                type: string
                example: "NJ"
            required:
              - city
              - state
        area_codes:
          type: array
          items:
            type: number
            example: 856
      required:
        - zip_code
        - city
        - state
        - lat
        - lng
    TimeZone:
      type: object
      properties:
        timezone_identifier:
          type: string
          example: "America/New_York"
        timezone_abbr:
          type: string
          example: "EDT"
        utc_offset_sec:
          type: integer
          example: -14400
        is_dst:
          type: string
          enum: ["T", "F"]
          description: |
            "T" if Daylight Saving Time is in effect, "F" otherwise.
      required:
        - timezone_identifier
        - timezone_abbr
        - utc_offset_sec
        - is_dst
      example:
        timezone_identifier: "America/New_York"
        timezone_abbr: "EDT"
        utc_offset_sec: -14400
        is_dst: "T"
    MatchCloseItem:
      type: object
      properties:
        zip_code1:
          type: string
          example: "12345"
        zip_code2:
          type: string
          example: "08057"
        distance:
          type: number
          format: float
          example: 123.45
      required:
        - zip_code1
        - zip_code2
        - distance

  responses:
    Error401:
      description: API key is missing or invalid. This includes if the application has not been activated yet.

    Error404:
      description: ZIP or postal code not found.

    Error429:
      description: API key usage exceeded.

    DistanceResponse:
      description: Distance between two ZIP codes
      content:
        application/json:
          schema:
            type: object
            properties:
              distance: { type: number }

    MultiDistanceResponse:
      description: Distance between primary ZIP code and each other zip code
      content:
        application/json:
          schema:
            type: object
            additionalProperties:
              type: number
              format: float
            example:
              "12345": 123.4
              "08057": 45.1

    MinimalRadiusResponse:
      description: ZIP codes within radius when minimal parameter is set.
      content:
        application/json:
          schema:
            type: object
            properties:
              zip_codes:
                type: array
                items:
                  type: string
                  pattern: '^\d{5}$'
            example:
              zip_codes:
                - "08057"
                - "08081"
                - "08055"

    RadiusResponse:
      description: ZIP codes within radius
      content:
        application/json:
          schema:
            type: object
            properties:
              zip_codes:
                type: array
                items:
                  type: object
                  properties:
                    zip_code:
                      type: string
                      pattern: '^\d{5}$'
                    distance:
                      type: number
                      format: float
                    city:
                      type: string
                    state:
                      type: string
                  required:
                    - zip_code
                    - distance
                    - city
                    - state

    MinimalCanadianRadiusResponse:
      description: Postal codes within radius when minimal parameter is set.
      content:
        application/json:
          schema:
            type: object
            properties:
              postal_codes:
                type: array
                items:
                  type: string
            example:
              postal_codes:
                - "A1A 1A1"
                - "A1A 1A2"

    SimpleCanadianRadiusResponse:
      description: Postal codes within radius when simple parameter is set. The index of the `distances` corresponds to the index of the `postal_codes`.
      content:
        application/json:
          schema:
            type: object
            properties:
              postal_codes:
                type: array
                items:
                  type: string
              distances:
                type: array
                items:
                  type: number
            example:
              postal_codes:
                - "A1A 1A1"
                - "A1A 1A2"
              distances:
                - 1.1
                - 2.5

    CanadianRadiusResponse:
      description: Postal codes within radius
      content:
        application/json:
          schema:
            type: object
            properties:
              postal_codes:
                type: array
                items:
                  type: object
                  properties:
                    postal_code:
                      type: string
                    distance:
                      type: number
                      format: float
                    city:
                      type: string
                    province:
                      type: string
                  required:
                    - postal_code
                    - distance
                    - city
                    - province

    InfoResponse:
      description: ZIP code info
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ZipCodeInfo'

    MultiInfoResponse:
      description: Info for multiple ZIP codes
      content:
        application/json:
          schema:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/ZipCodeInfo'

    CanadianInfoResponse:
      description: Canadian code info
      content:
        application/json:
          schema:
            type: object
            properties:
              postal_code: { type: string }
              city: { type: string }
              province: { type: string }
              lat: { type: number }
              lng: { type: number }
              acceptable_city_names:
                type: array
                items:
                  type: object
                  properties:
                    city:
                      type: string
                    province:
                      type: string
                  required:
                    - city
                    - province
            required:
              - postal_code
              - city
              - province
              - lat
              - lng

    CityZipsResponse:
      description: ZIP codes for a city/state
      content:
        application/json:
          schema:
            type: object
            properties:
              zip_codes:
                type: array
                items:
                  type: string
                  pattern: '^\d{5}$'

    CanadianCityPostalCodesResponse:
      description: Postal code for a city/province
      content:
        application/json:
          schema:
            type: object
            properties:
              zip_codes:
                type: array
                items:
                  type: string
                  pattern: '^[A-Z]\d[A-Z] \d[A-Z]\d$'

    MatchCloseResponse:
      description: Close ZIP codes
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/MatchCloseItem'

    StateZipCodesResponse:
      description: Zip codes for a state.
      content:
        application/json:
          schema:
            type: object
            properties:
              zip_codes:
                type: array
                items:
                  type: string
                  pattern: '^\d{5}$'