Name: City Geocoding API: Reverse Geocode to Nearest City
Brand: tidydata
SKU: api-tidydata-city-geocoding
Availability: InStock
Author: API Market

TidyData

# City Geocoding API

## Overview

The City Geocoding API works at city and town level over a built in set of 171,000 populated places, so every answer comes from the API itself rather than a rate limited upstream geocoder. It has three endpoints. /v1/geo/reverse takes a latitude and longitude and returns the nearest place, the nearest major city with 100,000 or more inhabitants, and a short list of alternatives. /v1/geo/search finds places by name with accent insensitive prefix matching, largest population first, with an optional country filter. /v1/geo/nearby lists every place within a radius of up to 500 km, sorted by distance.

Each place record includes a GeoNames ID, name, coordinates, ISO country code and country name, region, population, IANA time zone, a place type such as capital, seat or neighborhood, and the distance in km where relevant. That makes it a fit for apps that show a "you are near" label, tag photos and GPS tracks with place names, enrich analytics events with city and time zone, or offer a city picker with autocomplete. Results are city level, not street addresses. Place data is from GeoNames under CC BY 4.0, and each response carries the attribution line.

## Features

*   **Three endpoints**: Reverse geocode coordinates, search places by name, and list places within a radius.
*   **171,000 places**: Populated places worldwide with region names, population and IANA time zones.
*   **Nearest major city**: Reverse geocoding also returns the closest city with 100,000 or more inhabitants, useful when the nearest place is a small town or district.
*   **Population filter**: minPopulation on reverse and nearby skips small places so you get towns or cities of the size you want.
*   **Forgiving name search**: Accent insensitive prefix matching, largest places first, with an optional ISO country filter and 1 to 50 results.
*   **Time zone included**: Every place carries its IANA time zone, such as Europe/Madrid.
*   **10 requests per second**: All plans allow up to 10 requests per second, with no upstream geocoder limits on top.

## Use Cases

*   **Location labels in mobile apps**: Show "near Salamanca, Spain" from a device's GPS coordinates without sending users to a map service.
*   **Photo and GPS track tagging**: Add town, region, country and time zone to photos, rides and runs from their coordinates.
*   **City pickers and autocomplete**: Feed a city field with search results ranked by population and filtered by country.
*   **Analytics and data enrichment**: Turn raw coordinates in event or IoT data into city, country and local time zone for reporting.
*   **Delivery and local services**: List the towns within a delivery radius of a depot or store, nearest first.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/tidydata/city-geocoding
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Reverse geocode coordinates

Returns the nearest place to a latitude and longitude, the nearest major city of 100,000+ people and nearby alternatives, each with region, country, population, time zone and distance. Use minPopulation to skip small places.

**Method:** `GET`

**Endpoint:** `/v1/geo/reverse`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `lat` | query | Latitude | string | Yes | - | - |
| `lon` | query | Longitude | string | Yes | - | - |
| `minPopulation` | query | Only places with at least this population | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/city-geocoding/v1/geo/reverse?lat=40.4168&lon=-3.7038&minPopulation=0" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "query": {
    "lat": 40.4168,
    "lon": -3.7038
  },
  "nearest": {
    "geonameId": 6545083,
    "name": "Sol",
    "latitude": 40.4166,
    "longitude": -3.7033,
    "countryCode": "ES",
    "country": "Spain",
    "region": "Madrid",
    "population": 8164,
    "timezone": "Europe/Madrid",
    "type": "neighborhood",
    "distanceKm": 0.05
  },
  "nearestMajorCity": {
    "geonameId": 3117735,
    "name": "Madrid",
    "latitude": 40.4165,
    "longitude": -3.7026,
    "countryCode": "ES",
    "country": "Spain",
    "region": "Madrid",
    "population": 3255944,
    "timezone": "Europe/Madrid",
    "type": "capital",
    "distanceKm": 0.11
  },
  "alternatives": [
    {
      "geonameId": 3117735,
      "name": "Madrid",
      "latitude": 40.4165,
      "longitude": -3.7026,
      "countryCode": "ES",
      "country": "Spain",
      "region": "Madrid",
      "population": 3255944,
      "timezone": "Europe/Madrid",
      "type": "capital",
      "distanceKm": 0.11
    },
    {
      "geonameId": 6544494,
      "name": "Madrid Centro",
      "latitude": 40.4183,
      "longitude": -3.7027,
      "countryCode": "ES",
      "country": "Spain",
      "region": "Madrid",
      "population": 149718,
      "timezone": "Europe/Madrid",
      "type": "neighborhood",
      "distanceKm": 0.19
    },
    {
      "geonameId": 6545082,
      "name": "Las Cortes",
      "latitude": 40.4161,
      "longitude": -3.6967,
      "countryCode": "ES",
      "country": "Spain",
      "region": "Madrid",
      "population": 10816,
      "timezone": "Europe/Madrid",
      "type": "neighborhood",
      "distanceKm": 0.61
    }
  ],
  "attribution": "Place data © GeoNames (https://www.geonames.org), CC BY 4.0."
}
```

#### 2. Search places by name

Finds places whose name starts with q, ignoring accents, sorted by population, with an optional ISO country filter and a limit of 1 to 50.

**Method:** `GET`

**Endpoint:** `/v1/geo/search`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `q` | query | City or town name | string | Yes | - | - |
| `country` | query | Optional ISO country code filter | string | No | - | - |
| `limit` | query | 1-50 | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/city-geocoding/v1/geo/search?q=Salamanca&country=&limit=10" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "query": "Salamanca",
  "count": 7,
  "results": [
    {
      "geonameId": 3988214,
      "name": "Salamanca",
      "latitude": 20.5698,
      "longitude": -101.1977,
      "countryCode": "MX",
      "country": "Mexico",
      "region": "Guanajuato",
      "population": 160682,
      "timezone": "America/Mexico_City"
    },
    {
      "geonameId": 6544491,
      "name": "Salamanca",
      "latitude": 40.4297,
      "longitude": -3.6797,
      "countryCode": "ES",
      "country": "Spain",
      "region": "Madrid",
      "population": 147707,
      "timezone": "Europe/Madrid"
    },
    {
      "geonameId": 3111108,
      "name": "Salamanca",
      "latitude": 40.9688,
      "longitude": -5.6639,
      "countryCode": "ES",
      "country": "Spain",
      "region": "Castille and León",
      "population": 144825,
      "timezone": "Europe/Madrid"
    }
  ],
  "attribution": "Place data © GeoNames (https://www.geonames.org), CC BY 4.0."
}
```

#### 3. List places within a radius

Returns all places within a radius of up to 500 km around a point, sorted by distance, with optional minimum population and a limit of 1 to 100.

**Method:** `GET`

**Endpoint:** `/v1/geo/nearby`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `lat` | query | Latitude | string | Yes | - | - |
| `lon` | query | Longitude | string | Yes | - | - |
| `radius` | query | Radius in km (max 500) | string | No | - | - |
| `minPopulation` | query | Minimum population | string | No | - | - |
| `limit` | query | 1-100 | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/city-geocoding/v1/geo/nearby?lat=40.97&lon=-5.66&radius=25&minPopulation=1000&limit=20" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "query": {
    "lat": 40.97,
    "lon": -5.66,
    "radiusKm": 25,
    "minPopulation": 1000
  },
  "count": 10,
  "places": [
    {
      "geonameId": 3111108,
      "name": "Salamanca",
      "latitude": 40.9688,
      "longitude": -5.6639,
      "countryCode": "ES",
      "country": "Spain",
      "region": "Castille and León",
      "population": 144825,
      "timezone": "Europe/Madrid",
      "type": "county seat",
      "distanceKm": 0.35
    },
    {
      "geonameId": 3109721,
      "name": "Santa Marta de Tormes",
      "latitude": 40.9507,
      "longitude": -5.6272,
      "countryCode": "ES",
      "country": "Spain",
      "region": "Castille and León",
      "population": 14630,
      "timezone": "Europe/Madrid",
      "type": "seat",
      "distanceKm": 3.49
    },
    {
      "geonameId": 3126397,
      "name": "Carbajosa de la Sagrada",
      "latitude": 40.9331,
      "longitude": -5.6503,
      "countryCode": "ES",
      "country": "Spain",
      "region": "Castille and León",
      "population": 3467,
      "timezone": "Europe/Madrid",
      "type": "seat",
      "distanceKm": 4.18
    }
  ],
  "attribution": "Place data © GeoNames (https://www.geonames.org), CC BY 4.0."
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the result is in the response body. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. The body explains the problem. |
| 401 | Unauthorized | The `x-api-market-key` header is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The requested item or path does not exist. |
| 429 | Too Many Requests | You went over 10 requests per second or used up your plan quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Every plan allows 10 requests per second. The Pro plan includes 25,000 calls a month and the Ultra plan 150,000; when a monthly quota is used up, further calls return `429 Too Many Requests` until the next billing period. The pay-as-you-go plan has no quota and bills US$0.0005 per successful call. If you receive a `429`, back off before retrying and honour any `Retry-After` header.

## FAQ

**Does it return street addresses?**

No. This is city level geocoding. Reverse geocoding returns the nearest populated place, region and country, not a street or house number.

**Why did reverse geocoding return a neighborhood instead of the city?**

Some large cities are split into districts in the data, so the nearest place can be a neighborhood (for example Sol in central Madrid). Use the nearestMajorCity field, or raise minPopulation, to get the city itself.

**How does the name search match?**

It is a prefix match that ignores accents, so Leon also matches León. Results are sorted by population, largest first. Add country with an ISO code to narrow a common name such as Salamanca to one country.

**What is the maximum radius for nearby?**

500 km. You can return 1 to 100 places, sorted by distance, and filter out small places with minPopulation.

**Do I need to credit the data source?**

Place data comes from GeoNames under the CC BY 4.0 license, which requires attribution. Every response includes an attribution field you can show in your app.

**How much does the City Geocoding API cost?**

There is no free plan. Pay as you go costs US$0.0005 per call with no monthly fee. Pro is US$4.99 per month for 25,000 calls and Ultra is US$14.99 per month for 150,000 calls. All plans allow 10 requests per second.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Reverse geocoding API for 171,000 places: coordinates to nearest town, region, country and time zone, place search by name and places within a radius.