---
title: Search Places and Reverse Geocode API
slug: search-places-reverse-geocode
url: https://apyhub.com/modernsoftware-pro/service/search-places-reverse-geocode
provider: ModernSoftware.pro
categories: [Retrieval Kit, Verification Kit]
tags: [geocoding, reverse-geocoding, place-search, location-search, nearby-places, geo-ids]
auth: api_key
version: 1.0
service_type: sync
endpoints: 3
atoms: 25
mcp: true
---

# Search Places and Reverse Geocode API

Find places by name, reverse geocode coordinates, and list nearby places. Returns GeoNames-style records with country, region, timezone, and source metadata.

## Endpoints

| Method | URL | Description | Atoms |
| --- | --- | --- | --- |
| GET | `https://api.eu.apyhub.com/modernsoftware-pro/search-places-reverse-geocode/search` | Finds places by name. Finds up to 50 cities and populated places whose name starts with q in any st… | 25 |
| GET | `https://api.eu.apyhub.com/modernsoftware-pro/search-places-reverse-geocode/reverse` | Reverse geocoding: finds the place nearest to a coordinate. Given a GPS coordinate, returns the nea… | 25 |
| GET | `https://api.eu.apyhub.com/modernsoftware-pro/search-places-reverse-geocode/nearby` | Lists every known place within a radius of a coordinate. Given a GPS coordinate and a radius (in ki… | 25 |

## Endpoint reference

### Finds places by name.

`GET https://api.eu.apyhub.com/modernsoftware-pro/search-places-reverse-geocode/search` · 25 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `q` | query | string | yes | Name to search, in any supported language. |
| `country` | query | string | no | Optional country filter, ISO 3166-1 alpha-2 |
| `limit` | query | integer | no | Max results to return Default: `10`. |
| `lang` | query | string | no | Return additional `translations` for up to 2 languages: comma-separated 2-letter ISO-639 language codes (use 3-letter, if no 2-letter code exists) |

#### Quickstart

Search for a place by query text; this example looks up “Paris” and returns matching geocoding results.

```bash
curl -X GET "https://api.eu.apyhub.com/modernsoftware-pro/search-places-reverse-geocode/search?q=Paris&limit=3" \
  -H "apy-token: $APY_TOKEN"
```

#### What you'll get back

Returns a JSON object with `count`, `query`, `results`, and `sources`. `count` is the number of items in `results`; `query` is the trimmed search text; `results` is an array of place objects; and `sources` lists the data sources behind the returned results.

```json
{
  "query": "Paris",
  "count": 3,
  "results": [
    {
      "geonameId": 2988507,
      "wikidataId": "Q90",
      "nationalId": null,
      "name": "Paris",
      "officialNames": [
        {
          "language": "fr",
          "name": "Paris"
        }
      ],
      "latitude": 48.85341,
      "longitude": 2.3488,
      "countryCode": "FR",
      "country": "France",
      "region": "Île-de-France",
      "population": 2138551,
      "areaKm2": 105.4,
      "timezone": "Europe/Paris",
      "type": {
        "code": "PPLC",
        "label": "capital of a political entity"
      },
      "sources": [
        "geonames"
      ]
    },
    {
      "geonameId": 2970479,
      "wikidataId": null,
      "nationalId": null,
      "name": "Paris 15 Vaugirard",
      "officialNames": [
        {
          "language": "fr",
          "name": "Paris 15 Vaugirard"
        }
      ],
      "latitude": 48.8412,
      "longitude": 2.3003,
      "countryCode": "FR",
      "country": "France",
      "region": "Île-de-France",
      "population": 229713,
      "areaKm2": null,
      "timezone": "Europe/Paris",
      "type": {
        "code": "PPL",
        "label": "populated place"
      },
      "sources": [
        "geonames"
      ]
    },
    {
      "geonameId": 2994540,
      "wikidataId": null,
      "nationalId": null,
      "name": "Paris 20 Ménilmontant",
      "officialNames": [
        {
          "language": "fr",
          "name": "Paris 20 Ménilmontant"
        }
      ],
      "latitude": 48.8646,
      "longitude": 2.3984,
      "countryCode": "FR",
      "country": "France",
      "region": "Île-de-France",
      "population": 185140,
      "areaKm2": null,
      "timezone": "Europe/Paris",
      "type": {
        "code": "PPL",
        "label": "populated place"
      },
      "sources": [
        "geonames"
      ]
    }
  ],
  "sources": [
    {
      "id": "geonames",
      "name": "GeoNames.org",
      "license": "CC-BY-4.0",
      "attribution": null,
      "updatedAt": "2026-11-07"
    }
  ]
}
```

### Finds the place nearest to a coordinate.

`GET https://api.eu.apyhub.com/modernsoftware-pro/search-places-reverse-geocode/reverse` · 25 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `lat` | query | number (double) | yes | Latitude to query, between: -90.0 and 90.0 |
| `lon` | query | number (double) | yes | Longitude to query, between: -180.0 and 180.0 |
| `minPopulation` | query | integer | no | Only places with at least this population are considered (default 0, meaning no restriction). |
| `lang` | query | string | no | Return additional translations for up to 2 languages: comma-separated 2-letter ISO-639 language codes (use 3-letter, if no 2-letter code exists) |

#### Quickstart

Look up the nearest place for a latitude/longitude pair.

```bash
curl -X GET "https://api.eu.apyhub.com/modernsoftware-pro/search-places-reverse-geocode/reverse?lat=48.8566&lon=2.3522" \
  -H "apy-token: $APY_TOKEN"
```

#### What you'll get back

Returns a JSON object with `query`, `nearest`, `nearestMajorCity`, and `sources` fields. `query` echoes the requested coordinates; `nearest` and `nearestMajorCity` are objects or `null`; `sources` is an array of source metadata objects.

```json
{
  "query": {
    "lat": 48.8566,
    "lon": 2.3522
  },
  "nearest": {
    "geonameId": 3013131,
    "wikidataId": null,
    "nationalId": null,
    "name": "Paris 04 Hôtel-de-Ville",
    "officialNames": [
      {
        "language": "fr",
        "name": "Paris 04 Hôtel-de-Ville"
      }
    ],
    "latitude": 48.8601,
    "longitude": 2.3507,
    "countryCode": "FR",
    "country": "France",
    "region": "Île-de-France",
    "population": 27332,
    "areaKm2": null,
    "timezone": "Europe/Paris",
    "type": {
      "code": "PPL",
      "label": "populated place"
    },
    "sources": [
      "geonames"
    ],
    "distanceKm": 0.4
  },
  "nearestMajorCity": {
    "geonameId": 2988507,
    "wikidataId": "Q90",
    "nationalId": null,
    "name": "Paris",
    "officialNames": [
      {
        "language": "fr",
        "name": "Paris"
      }
    ],
    "latitude": 48.85341,
    "longitude": 2.3488,
    "countryCode": "FR",
    "country": "France",
    "region": "Île-de-France",
    "population": 2138551,
    "areaKm2": 105.4,
    "timezone": "Europe/Paris",
    "type": {
      "code": "PPLC",
      "label": "capital of a political entity"
    },
    "sources": [
      "geonames"
    ],
    "distanceKm": 0.43
  },
  "sources": [
    {
      "id": "geonames",
      "name": "GeoNames.org",
      "license": "CC-BY-4.0",
      "attribution": null,
      "updatedAt": "2026-11-07"
    }
  ]
}
```

### Lists every known place within a radius of a coordinate.

`GET https://api.eu.apyhub.com/modernsoftware-pro/search-places-reverse-geocode/nearby` · 25 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `lat` | query | number (double) | yes | Latitude to query, between -90.0 and 90.0 |
| `lon` | query | number (double) | yes | Longitude to query, between -180.0 and 180.0 |
| `radius` | query | number (double) | yes | Radius in km to search, 1-500. |
| `minPopulation` | query | integer | no | Only places with at least this population are considered (default 0, meaning no restriction). |
| `limit` | query | integer | no | Max result limit Default: `20`. |
| `lang` | query | string | no | Return additional `translations` for up to 2 languages: comma-separated 2-letter ISO-639 language codes (use 3-letter, if no 2-letter code exists) |

#### Quickstart

Find places near a coordinate by latitude, longitude, and search radius.

```bash
curl -X GET "https://api.eu.apyhub.com/modernsoftware-pro/search-places-reverse-geocode/nearby?lat=40.7128&lon=-74.006&radius=5" \
  -H "apy-token: $APY_TOKEN"
```

#### What you'll get back

Returns a JSON object with `query`, `count`, `places`, and `sources` fields. `query` is an object describing the normalized search inputs, `count` is the number of entries in `places`, `places` is an array of matched places, and `sources` lists the data sources behind the returned places.

```json
{
  "query": {
    "lat": 40.7128,
    "lon": -74.006,
    "radiusKm": 5,
    "minPopulation": 0
  },
  "count": 5,
  "places": [
    {
      "geonameId": 5128581,
      "wikidataId": "Q60",
      "nationalId": null,
      "name": "New York City",
      "officialNames": [
        {
          "language": "en",
          "name": "New York"
        }
      ],
      "latitude": 40.71427,
      "longitude": -74.00597,
      "countryCode": "US",
      "country": "United States of America",
      "region": "New York",
      "population": 8804190,
      "areaKm2": 778.18,
      "timezone": "America/New_York",
      "type": {
        "code": "PPL",
        "label": "populated place"
      },
      "sources": [
        "geonames"
      ],
      "distanceKm": 0.16
    },
    {
      "geonameId": 5141365,
      "wikidataId": "Q766014",
      "nationalId": null,
      "name": "Tribeca",
      "officialNames": [
        {
          "language": "en",
          "name": "TriBeCa"
        }
      ],
      "latitude": 40.71538,
      "longitude": -74.00931,
      "countryCode": "US",
      "country": "United States of America",
      "region": "New York",
      "population": 7811,
      "areaKm2": null,
      "timezone": "America/New_York",
      "type": {
        "code": "PPLX",
        "label": "section of populated place"
      },
      "sources": [
        "geonames"
      ],
      "distanceKm": 0.4
    },
    {
      "geonameId": 8436473,
      "wikidataId": "Q1050048",
      "nationalId": null,
      "name": "Financial District",
      "officialNames": [],
      "latitude": 40.70789,
      "longitude": -74.00857,
      "countryCode": "US",
      "country": "United States of America",
      "region": "New York",
      "population": 60976,
      "areaKm2": null,
      "timezone": "America/New_York",
      "type": {
        "code": "PPLX",
        "label": "section of populated place"
      },
      "sources": [
        "geonames"
      ],
      "distanceKm": 0.59
    },
    {
      "geonameId": 5108135,
      "wikidataId": "Q810961",
      "nationalId": null,
      "name": "Battery Park City",
      "officialNames": [],
      "latitude": 40.71149,
      "longitude": -74.01625,
      "countryCode": "US",
      "country": "United States of America",
      "region": "New York",
      "population": 7422,
      "areaKm2": null,
      "timezone": "America/New_York",
      "type": {
        "code": "PPLX",
        "label": "section of populated place"
      },
      "sources": [
        "geonames"
      ],
      "distanceKm": 0.88
    },
    {
      "geonameId": 5112540,
      "wikidataId": "Q866332",
      "nationalId": null,
      "name": "Chinatown",
      "officialNames": [],
      "latitude": 40.71649,
      "longitude": -73.99625,
      "countryCode": "US",
      "country": "United States of America",
      "region": "New York",
      "population": 90000,
      "areaKm2": null,
      "timezone": "America/New_York",
      "type": {
        "code": "PPLX",
        "label": "section of populated place"
      },
      "sources": [
        "geonames"
      ],
      "distanceKm": 0.92
    }
  ],
  "sources": [
    {
      "id": "geonames",
      "name": "GeoNames.org",
      "license": "CC-BY-4.0",
      "attribution": null,
      "updatedAt": "2026-11-07"
    }
  ]
}
```

## About

## What it does
Place Search API lets you look up places by name, find the nearest place to a coordinate, and list all known places within a radius. Send a search term, or a latitude and longitude, and get back structured place records with coordinates, country code, country, region, population, area, timezone, GeoNames and Wikidata identifiers, and source metadata.

Use the name search when you need to resolve user-entered place names into canonical records. The request accepts `q`, optional `country`, optional `limit`, and optional `lang`. The response includes the trimmed `query`, a `count`, a `results` array, and the contributing `sources`. Each result includes `name`, `officialNames`, `latitude`, `longitude`, `countryCode`, `country`, `region`, `population`, `areaKm2`, `timezone`, `type`, and source identifiers, plus optional translation data when you pass `lang`.

Use the coordinate lookup when you need reverse geocoding with context. It accepts `lat`, `lon`, optional `minPopulation`, and optional `lang`, and returns the nearest place plus the nearest major city with a population of at least 100,000 when available. For spatial search, send `lat`, `lon`, `radius`, optional `minPopulation`, optional `limit`, and optional `lang` to list matching places within the radius. Those responses include the requested coordinate as `query`, a `count`, the matching `places`, and the shared `sources` metadata.

This is a good fit for location autocomplete, map pin labeling, nearby-city detection, address normalization, and analytics that need consistent place IDs rather than free-text names.

## Usage

Base URL: `https://api.eu.apyhub.com` (default region — see
`GET https://apyhub.com/api/public/regions` for the rest).

Authenticate with an ApyHub API key in the `apy-token` header.
Full docs and a live playground: https://apyhub.com/modernsoftware-pro/service/search-places-reverse-geocode