api-ninjas-com Geocoding API

openapi: 3.2.0
info:
  title: Ninjas Geocoding 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: Geocoding
  description: 'The Geocoding API converts between place names and coordinates in both directions: /geocoding turns a city, state, or US ZIP code into latitude and longitude, and /reversegeocoding turns coordinates back into the nearest city, state, and country. Both resolve place names, not street addresses. Results are enriched well beyond the coordinate pair: every lookup also returns the administrative hierarchy with ISO 3166-2 codes, IANA timezone, population, elevation, country context (currency, calling code, languages, EU/EEA membership) and alternative coordinate formats such as Plus Codes and geohash. Premium subscribers additionally receive climate zone, degree of urbanisation, land/water status and the nearest airport.'
paths:
  /v1/geocoding:
    get:
      tags:
      - Geocoding
      summary: Get coordinates for a city, state, or US ZIP code
      description: Converts a place name into latitude and longitude. Requires `city`; narrow with `state`, `country` or `zipcode`. For the reverse direction use /reversegeocoding.
      operationId: getGeocoding
      parameters:
      - $ref: '#/components/parameters/city'
      - $ref: '#/components/parameters/state'
      - $ref: '#/components/parameters/country'
      - $ref: '#/components/parameters/zipcode'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingOpenapi_ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingOpenapi_ErrorResponse'
      security:
      - ApiKeyAuth: []
  /v1/reversegeocoding:
    get:
      summary: Convert latitude/longitude coordinates to city locations
      description: Converts a `lat` and `lon` pair into the matching place name and administrative area. For the opposite direction use /geocoding.
      operationId: getReverseGeocoding
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      responses:
        '200':
          description: A list of cities that contain the given latitude and longitude.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReverseGeocodingResponse'
        '400':
          description: Bad Request - The request was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingOpenapi_ErrorResponse'
        '401':
          description: Unauthorized - API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingOpenapi_ErrorResponse'
        '500':
          description: Internal Server Error - We had a problem with our server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingOpenapi_ErrorResponse'
      tags:
      - Geocoding
components:
  schemas:
    GeocodingOpenapi_ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message.
    GeocodingResponse:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
            description: Name of the city.
          latitude:
            type: number
            format: double
            description: Latitude coordinate of the city.
          longitude:
            type: number
            format: double
            description: Longitude coordinate of the city.
          country:
            type: string
            description: ISO country code of the city.
          state:
            type: string
            description: State, province, or region of the city (e.g. England).
          admin1_name:
            type:
            - string
            - 'null'
            description: First-level administrative division name (state, province, region). e.g. "England".
          admin1_iso:
            type:
            - string
            - 'null'
            description: ISO 3166-2 code for the first-level division. e.g. "GB-ENG".
          admin2_name:
            type:
            - string
            - 'null'
            description: Second-level administrative division (county or equivalent).
          timezone:
            type:
            - string
            - 'null'
            description: IANA timezone name. e.g. "Europe/London".
          population:
            type:
            - integer
            - 'null'
            description: Population of the matched place.
          elevation_m:
            type:
            - integer
            - 'null'
            description: Elevation in metres of the matched place.
          country_name:
            type:
            - string
            - 'null'
            description: Full country name.
          iso3:
            type:
            - string
            - 'null'
            description: ISO 3166-1 alpha-3 country code.
          iso_numeric:
            type:
            - string
            - 'null'
            description: ISO 3166-1 numeric country code.
          capital:
            type:
            - string
            - 'null'
            description: Capital city.
          continent:
            type:
            - string
            - 'null'
            description: Two-letter continent code.
          region:
            type:
            - string
            - 'null'
            description: UN M49 region name.
          subregion:
            type:
            - string
            - 'null'
            description: UN M49 sub-region name.
          currency:
            type:
            - string
            - 'null'
            description: ISO 4217 currency code.
          currency_name:
            type:
            - string
            - 'null'
            description: Currency name.
          calling_code:
            type:
            - string
            - 'null'
            description: International dialling prefix. e.g. "+44".
          languages:
            type:
            - string
            - 'null'
            description: Comma-separated BCP-47 language tags.
          tld:
            type:
            - string
            - 'null'
            description: Country-code top-level domain.
          driving_side:
            type:
            - string
            - 'null'
            description: '"left" or "right".'
          is_eu:
            type:
            - boolean
            - 'null'
            description: Whether the country is an EU member state.
          is_eea:
            type:
            - boolean
            - 'null'
            description: Whether the country is in the European Economic Area.
          plus_code:
            type:
            - string
            - 'null'
            description: Open Location Code (Plus Code) for the coordinate.
          geohash:
            type:
            - string
            - 'null'
            description: 9-character geohash.
          dms:
            type:
            - object
            - 'null'
            description: Degrees/minutes/seconds representation.
            properties:
              latitude:
                type: string
              longitude:
                type: string
          mercator:
            type:
            - object
            - 'null'
            description: Web Mercator (EPSG:3857) coordinates in metres.
            properties:
              x:
                type: number
              y:
                type: number
          antipode:
            type:
            - object
            - 'null'
            description: The point diametrically opposite on the globe.
            properties:
              latitude:
                type: number
              longitude:
                type: number
          hemisphere:
            type:
            - object
            - 'null'
            description: Hemisphere indicators.
            properties:
              north_south:
                type: string
              east_west:
                type: string
          qibla_degrees:
            type:
            - number
            - 'null'
            description: Bearing to the Kaaba in Mecca, degrees clockwise from true north.
          sun:
            type:
            - object
            - 'null'
            description: Sunrise, sunset, solar noon and twilight times for today (UTC).
            properties:
              sunrise:
                type:
                - string
                - 'null'
              sunset:
                type:
                - string
                - 'null'
              solar_noon:
                type:
                - string
                - 'null'
              civil_dawn:
                type:
                - string
                - 'null'
              civil_dusk:
                type:
                - string
                - 'null'
              nautical_dawn:
                type:
                - string
                - 'null'
              nautical_dusk:
                type:
                - string
                - 'null'
              astronomical_dawn:
                type:
                - string
                - 'null'
              astronomical_dusk:
                type:
                - string
                - 'null'
          climate_zone:
            type:
            - string
            - 'null'
            description: 'Köppen-Geiger climate classification code. e.g. "Cfb". Premium field: Free, Learner and Developer tiers receive a notice string in place of the value.'
          climate_zone_name:
            type:
            - string
            - 'null'
            description: 'Human-readable climate classification. Premium field: Free, Learner and Developer tiers receive a notice string in place of the value.'
          urbanisation:
            type:
            - string
            - 'null'
            description: 'GHSL degree-of-urbanisation class: URBAN_CENTRE, DENSE_URBAN_CLUSTER, SEMI_DENSE_URBAN, SUBURBAN, RURAL_CLUSTER, LOW_DENSITY_RURAL, VERY_LOW_DENSITY_RURAL or WATER. Premium field: Free, Learner and Developer tiers receive a notice string in place of the value.'
          urbanisation_name:
            type:
            - string
            - 'null'
            description: 'Human-readable urbanisation class. Premium field: Free, Learner and Developer tiers receive a notice string in place of the value.'
          is_land:
            type:
            - boolean
            - 'null'
            description: 'Whether the coordinate falls on land. Inland water counts as not land. Premium field: Free, Learner and Developer tiers receive a notice string in place of the value.'
          nearest_airport:
            type:
            - object
            - 'null'
            description: 'Nearest airport carrying an IATA code, with distance and bearing. Premium field: Free, Learner and Developer tiers receive 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
          county:
            type:
            - string
            - 'null'
            description: US county. Business tier and above.
          zip_code:
            type:
            - string
            - 'null'
            description: 'US ZIP code of the matched place. See zip_code_accuracy — this is not a point-in-polygon result. Premium field: Free, Learner and Developer tiers receive a notice string in place of the value.'
          zip_code_accuracy:
            type:
            - string
            - 'null'
            description: 'How zip_code was derived: "exact" (the ZIP was the input), "place_centroid" (the matched place''s ZIP), or "nearest" (nearest ZIP centroid). Premium field: Free, Learner and Developer tiers receive a notice string in place of the value.'
          area_codes:
            type:
            - array
            - 'null'
            description: 'US telephone area codes serving the location. Premium field: Free, Learner and Developer tiers receive a notice string in place of the value.'
            items:
              type: string
        required:
        - name
        - latitude
        - longitude
        - country
    ReverseGeocodingResponse:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
            description: The name of the city.
          country:
            type: string
            description: The ISO country code.
          state:
            type: string
            description: The state or region of the city.
          county:
            type:
            - string
            - 'null'
            description: US county containing the location (e.g. San Francisco County). Returned on every response. Premium subscribers see the value; other tiers receive a notice string.
          zip_code:
            type:
            - string
            - 'null'
            description: US ZIP code for the location. Premium only.
          area_codes:
            type:
            - array
            - 'null'
            items:
              type: string
            description: US telephone area codes serving the location. Premium only.
          timezone:
            type:
            - string
            - 'null'
            description: IANA timezone name. Premium only.
        required:
        - name
        - country
        - state
  parameters:
    Longitude:
      name: lon
      in: query
      description: Longitude coordinate.
      required: true
      schema:
        type: number
        format: double
    state:
      name: state
      in: query
      description: US state (for United States cities only).
      required: false
      schema:
        type: string
    city:
      name: city
      in: query
      description: City name.
      required: true
      schema:
        type: string
    zipcode:
      name: zipcode
      in: query
      description: 5-digit zipcode (for United States cities only).
      required: false
      schema:
        type: string
    Latitude:
      name: lat
      in: query
      description: Latitude coordinate.
      required: true
      schema:
        type: number
        format: double
    country:
      name: country
      in: query
      description: Country name, 2-letter ISO country code, or 3-letter ISO country code.
      required: false
      schema:
        type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api