api-ninjas-com Zip Code API

openapi: 3.2.0
info:
  title: Ninjas Zip Code API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Zip Code
  description: The Zip Code API enables you to look up detailed information for every ZIP Code in the United States. You can input ZIP Codes directly, or search for ZIP Codes using city and state parameters.
paths:
  /v1/zipcode:
    get:
      summary: Get ZIP Code details
      description: Returns a list of ZIP Code details matching the input parameters.
      parameters:
      - name: zip
        in: query
        description: The ZIP Code to look up.
        required: false
        schema:
          type: string
      - name: city
        in: query
        description: Full name of the city to search (case-sensitive). Premium subscribers only.
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: 2-letter abbreviation of the state (case-insensitive). Premium subscribers only.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZipCodeResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
      tags:
      - Zip Code
      operationId: getV1Zipcode
      x-operation-id-source: derived
components:
  schemas:
    ZipCodeResponse:
      type: array
      items:
        type: object
        properties:
          zip_code:
            type: string
            example: '97201'
          valid:
            type: boolean
            example: true
          city:
            type: string
            example: Portland
          state:
            type: string
            example: OR
          county:
            type: string
            example: Multnomah County
          timezone:
            type: string
            example: America/Los_Angeles
          area_codes:
            type: array
            items:
              type: string
            example:
            - '503'
            - '971'
          country:
            type: string
            example: US
          lat:
            type: string
            example: '45.5074'
          lon:
            type: string
            example: '-122.6898'
          population:
            type:
            - integer
            - 'null'
            description: 'Population of the nearest populated place to the ZIP centroid. Premium field: the Free tier receives a notice string in place of the value.'
          elevation_m:
            type:
            - integer
            - 'null'
            description: 'Elevation in metres of the nearest populated place. Premium field: the Free tier receives a notice string in place of the value.'
          climate_zone:
            type:
            - string
            - 'null'
            description: 'Köppen-Geiger climate classification code, e.g. Csa. Premium field: the Free tier receives a notice string in place of the value.'
          urbanisation:
            type:
            - string
            - 'null'
            description: 'Degree of urbanisation, from URBAN_CENTRE to VERY_LOW_DENSITY_RURAL. Premium field: the Free tier receives a notice string in place of the value.'
          nearest_airport:
            type:
            - object
            - 'null'
            description: 'Nearest IATA-coded airport with distance and bearing. Premium field: the Free tier receives a notice string in place of the value.'
            properties:
              name:
                type: string
              iata:
                type: string
              icao:
                type: string
              country:
                type: string
              municipality:
                type: string
              type:
                type: string
              scheduled_service:
                type: boolean
              latitude:
                type: number
              longitude:
                type: number
              elevation_m:
                type:
                - integer
                - 'null'
              distance_km:
                type: number
              bearing_degrees:
                type: number
          zcta:
            type:
            - string
            - 'null'
            description: ZIP Code Tabulation Area.
            example: '90210'
          land_area_sqmi:
            type:
            - number
            - 'null'
            description: Land area of the ZCTA in square miles.
            example: 10.748
          water_area_sqmi:
            type:
            - number
            - 'null'
            description: Water area of the ZCTA in square miles.
            example: 0.054
          state_fips:
            type:
            - string
            - 'null'
            description: 2-digit state FIPS code.
            example: '06'
          county_fips:
            type:
            - string
            - 'null'
            description: 5-digit FIPS code of the predominant county.
            example: '06037'
          tract_fips:
            type:
            - string
            - 'null'
            description: 11-digit FIPS code of the predominant Census tract.
            example: '06037261102'
          counties:
            type: array
            items:
              type: object
              properties:
                fips:
                  type: string
                name:
                  type: string
                land_share:
                  type: number
                  description: Share of the ZIP Code’s land area falling in this area.
            example:
            - fips: '06037'
              name: Los Angeles County
              land_share: 1
            description: Every county the ZIP Code overlaps. ~30% span more than one.
          cbsa_code:
            type:
            - string
            - 'null'
            description: Core Based Statistical Area code (OMB 2023).
            example: '31080'
          cbsa_title:
            type:
            - string
            - 'null'
            description: CBSA name.
            example: Los Angeles-Long Beach-Anaheim, CA
          cbsa_type:
            type:
            - string
            - 'null'
            description: Either metro or micro.
            enum:
            - metro
            - micro
            - null
            example: metro
          csa_code:
            type:
            - string
            - 'null'
            description: Combined Statistical Area code.
            example: '348'
          csa_title:
            type:
            - string
            - 'null'
            description: CSA name.
            example: Los Angeles-Long Beach, CA
          timezones:
            type: array
            description: IANA timezones covering the ZIP Code. More than one means the county is split.
            items:
              type: string
            example:
            - America/Los_Angeles
          observes_dst:
            type:
            - boolean
            - 'null'
            description: Whether daylight saving is observed.
            example: true
          timezone_is_split:
            type:
            - boolean
            - 'null'
            description: True when the county is divided by a timezone or DST boundary.
            example: false
          utc_offset_std:
            type:
            - string
            - 'null'
            description: Standard-time UTC offset.
            example: -08:00
          utc_offset_current:
            type:
            - string
            - 'null'
            description: UTC offset in effect now, resolved per request.
            example: -07:00
          is_dst_now:
            type:
            - boolean
            - 'null'
            description: Whether daylight saving is currently in effect.
            example: true
          school_districts:
            type: array
            items:
              type: object
              properties:
                leaid:
                  type: string
                name:
                  type: string
                type:
                  type: string
                land_share:
                  type: number
                  description: Share of the ZIP Code’s land area falling in this area.
            example:
            - leaid: '0622710'
              name: Los Angeles Unified School District
              type: unified
              land_share: 0.5933
            description: Every overlapping school district. 61% of ZIP Codes touch more than one.
          primary_school_district:
            type:
            - string
            - 'null'
            description: District covering the largest share.
            example: Los Angeles Unified School District
          primary_school_district_leaid:
            type:
            - string
            - 'null'
            description: NCES LEAID of the primary district.
            example: '0622710'
          congressional_districts:
            type: array
            items:
              type: object
              properties:
                district:
                  type: string
                name:
                  type: string
                land_share:
                  type: number
                  description: Share of the ZIP Code’s land area falling in this area.
            example:
            - district: '0632'
              name: Congressional District 32
              land_share: 0.6231
            description: Every overlapping congressional district. ~15% of ZIP Codes span more than one.
          congressional_district_vintage:
            type:
            - string
            - 'null'
            description: Which congressional boundary set the districts reflect.
            example: cd119
          state_legislative_upper:
            type: array
            items:
              type: object
              properties:
                district:
                  type: string
                name:
                  type: string
                land_share:
                  type: number
                  description: Share of the ZIP Code’s land area falling in this area.
            example:
            - district: '06024'
              name: State Senate District 24
              land_share: 0.9432
          state_legislative_lower:
            type: array
            items:
              type: object
              properties:
                district:
                  type: string
                name:
                  type: string
                land_share:
                  type: number
                  description: Share of the ZIP Code’s land area falling in this area.
            example:
            - district: '06051'
              name: Assembly District 51
              land_share: 0.6445
            description: State house districts. Nebraska is unicameral and returns none.
          demographics:
            type:
            - object
            - 'null'
            description: ACS 2020-2024 5-year estimates for the ZCTA.
            properties:
              population:
                type: integer
              median_age:
                type: number
              median_household_income:
                type:
                - integer
                - 'null'
              per_capita_income:
                type:
                - integer
                - 'null'
              median_home_value:
                type:
                - integer
                - 'null'
              median_gross_rent:
                type:
                - integer
                - 'null'
              housing_units:
                type: integer
              owner_occupied_pct:
                type:
                - number
                - 'null'
              poverty_rate:
                type:
                - number
                - 'null'
              unemployment_rate:
                type:
                - number
                - 'null'
              bachelors_or_higher_pct:
                type:
                - number
                - 'null'
              mean_commute_minutes:
                type:
                - number
                - 'null'
              estimate_flags:
                type: array
                items:
                  type: string
                description: Names any median that fell in an open-ended top or bottom category, where the value is the category bound rather than a true median.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api