NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

Geocoding & Reverse Geocoding API

The Geocoding API converts between place names and geographic coordinates in both directions. It resolves cities, towns, and US ZIP codes — not street addresses.

Every lookup returns the administrative hierarchy with ISO 3166-2 codes, IANA timezone, population and elevation, and country context such as currency, calling code, languages and EU/EEA membership — plus alternative coordinate formats including Plus Codes and geohash. Premium subscribers additionally receive climate zone, degree of urbanisation and the nearest airport.

Available endpoints:

  • /v1/geocoding - Convert a city, state, or US ZIP code to latitude and longitude coordinates
  • /v1/reversegeocoding - Convert latitude and longitude coordinates to the nearest city, state, and country
(4.5)

From 2,473 users

700+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average
P50
P75
P90
P95
194ms239ms287ms671ms873ms

Didn't find what you were looking for? Suggest an improvement

https://api.api-ninjas.com/v1/geocoding

Get current city coordinates by city and country name.

Parameters

At least one of the following parameters must be set:

  • city  required

    City name.

  • state  optional

    US state (for United States cities only).

  • country  optional

    Country name, 2-letter ISO country code, or 3-letter ISO country code.

  • zipcode  optional

    5-digit zipcode (for United States cities only).

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON array of objects, each containing the following fields, or an error if the request is unsuccessful.

Core
  • name

    The name of the matched place.

  • latitude

    Latitude coordinate in WGS 84 decimal degrees.

  • longitude

    Longitude coordinate in WGS 84 decimal degrees.

  • country

    2-letter ISO 3166-1 alpha-2 country code.

  • state

    State, province or region of the place. Not returned for all locations.

Place
  • admin1_name

    First-level administrative division — state, province or region (e.g. England).

  • admin1_iso

    ISO 3166-2 code for that division (e.g. GB-ENG).

  • admin2_name

    Second-level division — county or equivalent. Available for about 86% of places worldwide; sparse in Germany and Russia.

  • timezone

    IANA timezone name (e.g. Europe/London).

  • population

    Population of the matched place.

  • elevation_m

    Elevation of the matched place in metres. Surveyed where available, otherwise the SRTM DEM value for the settlement — not a per-coordinate sample.

Country
  • country_name

    Full country name.

  • iso3

    ISO 3166-1 alpha-3 country code.

  • iso_numeric

    ISO 3166-1 numeric country code.

  • capital

    Capital city.

  • continent

    Two-letter continent code.

  • region

    UN M49 region name.

  • subregion

    UN M49 sub-region name.

  • currency

    ISO 4217 currency code.

  • currency_name

    Currency name.

  • calling_code

    International dialling prefix (e.g. +44).

  • languages

    Comma-separated BCP-47 language tags.

  • tld

    Country-code top-level domain.

  • driving_side

    left or right.

  • is_eu

    Whether the country is an EU member state.

  • is_eea

    Whether the country is in the European Economic Area.

Coordinate formats
  • plus_code

    Open Location Code (Plus Code) for the coordinate.

  • geohash

    9-character geohash.

  • dms

    Degrees/minutes/seconds strings for latitude and longitude.

  • mercator

    Web Mercator (EPSG:3857) x and y in metres.

  • antipode

    The point diametrically opposite on the globe.

  • hemisphere

    North/south and east/west indicators.

  • qibla_degrees

    Bearing to the Kaaba in Mecca, degrees clockwise from true north.

  • osm

    OpenStreetMap view, edit and note URLs.

  • sun

    Sunrise, sunset, solar noon, the three twilight bands and day length for today in UTC. Sub-values are null above the polar circles, where polar_day and polar_night say why.

Environment
  • climate_zone  premium only

    Köppen-Geiger climate code (e.g. Cfb).

  • climate_zone_name  premium only

    Human-readable climate classification.

  • urbanisation  premium only

    GHSL degree-of-urbanisation class, from URBAN_CENTRE through VERY_LOW_DENSITY_RURAL to WATER.

  • urbanisation_name  premium only

    Human-readable urbanisation class.

  • is_land  premium only

    Whether the coordinate is on land. Inland water counts as not land.

  • nearest_airport  premium only

    Nearest IATA-coded airport, with distance and bearing.

United States only
  • county  premium only

    US county. Returned only from an authoritative match — null rather than a guess.

  • zip_code  premium only

    US ZIP code of the matched place. See zip_code_accuracy; this is not a point-in-polygon result.

  • zip_code_accuracy  premium only

    How zip_code was derived: exact, place_centroid or nearest.

  • area_codes  premium only

    US telephone area codes serving the location.

Sample Request Live Demo!

city
state
country
zipcode

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

https://api.api-ninjas.com/v1/geocoding?city=London&country=GB

Headers

X-Api-KeyLog in or sign up to get your API Key

Sample Response

JSON
[
    {
      name:"London",
      latitude:51.5074456,
      longitude:-0.1277653,
      country:"GB",
      state:"England",
      admin1_name:"England",
      admin1_iso:"GB-ENG",
      admin2_name:"Greater London",
      timezone:"Europe/London",
      population:8961989,
      elevation_m:25,
      country_name:"United Kingdom",
      iso3:"GBR",
      capital:"London",
      continent:"EU",
      region:"Europe",
      currency:"GBP",
      calling_code:"+44",
      languages:"en-GB,cy-GB,gd",
      driving_side:"left",
      is_eu:false,
      plus_code:"9C3XGV4C+XV",
      geohash:"gcpvj0duw",
      climate_zone:"Cfb",
      climate_zone_name:"Temperate, no dry season, warm summer",
      urbanisation:"URBAN_CENTRE",
      is_land:true,
      nearest_airport:{
        name:"London City Airport",
        iata:"LCY",
        icao:"EGLC",
        country:"GB",
        municipality:"London",
        type:"medium_airport",
        scheduled_service:true,
        latitude:51.505299,
        longitude:0.055278,
        elevation_m:6,
        distance_km:12.67,
        bearing_degrees:91
      },
      county:null,
      zip_code:null,
      zip_code_accuracy:null,
      area_codes:null
    }
]

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/geocoding?city=London&country=GB" \ -H "X-Api-Key: YOUR_API_KEY"

If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.

https://api.api-ninjas.com/v1/reversegeocoding

Returns a list of cities that contain a given latitude and longitude.

Parameters

  • lat  required

    Latitude coordinate.

  • lon  required

    Longitude coordinate.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON array of location objects, each containing the following fields, or an error if the request is unsuccessful.

Core
  • name

    The name of the nearest matched place.

  • country

    2-letter ISO 3166-1 alpha-2 country code.

  • state

    State, province or region. Not returned for all locations.

Place
  • admin1_name

    First-level administrative division — state, province or region (e.g. England).

  • admin1_iso

    ISO 3166-2 code for that division (e.g. GB-ENG).

  • admin2_name

    Second-level division — county or equivalent. Available for about 86% of places worldwide; sparse in Germany and Russia.

  • timezone

    IANA timezone name (e.g. Europe/London).

  • population

    Population of the matched place.

  • elevation_m

    Elevation of the matched place in metres. Surveyed where available, otherwise the SRTM DEM value for the settlement — not a per-coordinate sample.

Country
  • country_name

    Full country name.

  • iso3

    ISO 3166-1 alpha-3 country code.

  • iso_numeric

    ISO 3166-1 numeric country code.

  • capital

    Capital city.

  • continent

    Two-letter continent code.

  • region

    UN M49 region name.

  • subregion

    UN M49 sub-region name.

  • currency

    ISO 4217 currency code.

  • currency_name

    Currency name.

  • calling_code

    International dialling prefix (e.g. +44).

  • languages

    Comma-separated BCP-47 language tags.

  • tld

    Country-code top-level domain.

  • driving_side

    left or right.

  • is_eu

    Whether the country is an EU member state.

  • is_eea

    Whether the country is in the European Economic Area.

Coordinate formats
  • plus_code

    Open Location Code (Plus Code) for the coordinate.

  • geohash

    9-character geohash.

  • dms

    Degrees/minutes/seconds strings for latitude and longitude.

  • mercator

    Web Mercator (EPSG:3857) x and y in metres.

  • antipode

    The point diametrically opposite on the globe.

  • hemisphere

    North/south and east/west indicators.

  • qibla_degrees

    Bearing to the Kaaba in Mecca, degrees clockwise from true north.

  • osm

    OpenStreetMap view, edit and note URLs.

  • sun

    Sunrise, sunset, solar noon, the three twilight bands and day length for today in UTC. Sub-values are null above the polar circles, where polar_day and polar_night say why.

Environment
  • climate_zone  premium only

    Köppen-Geiger climate code (e.g. Cfb).

  • climate_zone_name  premium only

    Human-readable climate classification.

  • urbanisation  premium only

    GHSL degree-of-urbanisation class, from URBAN_CENTRE through VERY_LOW_DENSITY_RURAL to WATER.

  • urbanisation_name  premium only

    Human-readable urbanisation class.

  • is_land  premium only

    Whether the coordinate is on land. Inland water counts as not land.

  • nearest_airport  premium only

    Nearest IATA-coded airport, with distance and bearing.

United States only
  • county  premium only

    US county. Returned only from an authoritative match — null rather than a guess.

  • zip_code  premium only

    US ZIP code of the matched place. See zip_code_accuracy; this is not a point-in-polygon result.

  • zip_code_accuracy  premium only

    How zip_code was derived: exact, place_centroid or nearest.

  • area_codes  premium only

    US telephone area codes serving the location.

Sample Request Live Demo!

lat
lon

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

https://api.api-ninjas.com/v1/reversegeocoding?lat=51.509865&lon=-0.118092

Headers

X-Api-KeyLog in or sign up to get your API Key

Sample Response

JSON
[
    {
      name:"City of Westminster",
      country:"GB",
      state:"England",
      admin1_name:"England",
      admin1_iso:"GB-ENG",
      admin2_name:"Greater London",
      timezone:"Europe/London",
      population:8961989,
      elevation_m:25,
      country_name:"United Kingdom",
      iso3:"GBR",
      capital:"London",
      continent:"EU",
      region:"Europe",
      currency:"GBP",
      calling_code:"+44",
      languages:"en-GB,cy-GB,gd",
      driving_side:"left",
      is_eu:false,
      plus_code:"9C3XGV4C+XW",
      geohash:"gcpvj0eh2",
      climate_zone:"Cfb",
      climate_zone_name:"Temperate, no dry season, warm summer",
      urbanisation:"URBAN_CENTRE",
      is_land:true,
      nearest_airport:{
        name:"London City Airport",
        iata:"LCY",
        icao:"EGLC",
        country:"GB",
        municipality:"London",
        type:"medium_airport",
        scheduled_service:true,
        latitude:51.505299,
        longitude:0.055278,
        elevation_m:6,
        distance_km:12.67,
        bearing_degrees:91
      },
      county:null,
      zip_code:null,
      zip_code_accuracy:null,
      area_codes:null
    }
]

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/reversegeocoding?lat=40.7128&lon=-74.0060" \ -H "X-Api-Key: YOUR_API_KEY"

If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.

Frequently Asked Questions

  • Yes, but you must have a premium subscription. Commercial use of the Geocoding API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.
  • Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.
  • Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.
  • The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.
  • It is ideal for translating raw GPS or device lat/lon coordinates into human-readable place names for ride-sharing apps, delivery tracking, store locators, and analytics dashboards. For the opposite direction (turning a place name into coordinates), use the Geocoding API.
  • Send a GET request to the /v1/reversegeocoding endpoint with the required lat and lon query parameters, for example ?lat=40.7128&lon=-74.0060. See the pricing page for request limits per plan.
  • It returns a JSON array of location objects, each with a name (city, town, or area), a country field as a 2-letter ISO 3166 alpha-2 code, and a state field for the province or administrative region. If you also need detailed city statistics like population, pair it with the City API.
  • The Reverse Geocoding API only accepts lat and lon coordinates, so to derive a location from a visitor's IP first use the IP Lookup API, and to find the time zone for a set of coordinates use the Timezone API.
  • Pass the country parameter alongside city — it accepts a country name, a 2-letter ISO code, or a 3-letter ISO code (for example country=GB for London). For United States cities you can further narrow results with the state parameter or a 5-digit zipcode. Browse related location tools in the API catalog.
  • It returns a JSON array of objects, each containing the city name, its latitude and longitude coordinates, and the 2-letter ISO 3166 alpha-2 country code. Failed requests return an error instead, as described in our error codes documentation.
  • The Geocoding endpoint only converts forward, from a city to its latitude and longitude; to go the other direction and resolve coordinates into a location, use our Reverse Geocoding endpoint instead.
  • This endpoint returns only name, latitude, longitude, and country; for richer data such as population or region, use the City API, or look up the local time at those coordinates with the Timezone API.