---
title: "Geocoding API"
description: "Turn place names into coordinates, and coordinates back into place names."
canonical_url: "http://0.0.0.0:6006/geocoding"
markdown_url: "http://0.0.0.0:6006/geocoding.md"
last_updated: "2026-11-17"
x_farming_labs_generated_preamble: true
---

# Geocoding API
URL: /geocoding
LLM index: /llms.txt
Description: Turn place names into coordinates, and coordinates back into place names.

# Geocoding API

The Geocoding API works in both directions. Forward geocoding takes text like `Bole Road` and returns where it is. Reverse geocoding takes a point like `9.0192, 38.7578` and returns what is there, from a single address up to the city and country around it.

<Callout title="Autocomplete is forward geocoding">
  An autocomplete or search-as-you-type box is built on [forward
  geocoding](/geocoding/geocoding-forward): call it with the text typed so far and show the results
  as suggestions. There is no separate autocomplete API. This is different from the `autocomplete`
  parameter, which only controls whether partial words match.
</Callout>

<Cards>
  <Card
    title="Forward geocoding"
    description="Search by name or address and get coordinates back."
    href="/geocoding/geocoding-forward"
  />
  <Card
    title="Reverse geocoding"
    description="Send coordinates and get the place or address at that point."
    href="/geocoding/geocoding-reverse"
  />
</Cards>

## When to use it

<Cards>
  <Card icon={<MagnifyingGlassIcon />} title="Search boxes">
    Turn what a user types into a point on the map, with autocomplete as they type.
  </Card>
  <Card icon={<SewingPinIcon />} title="Labels">
    Show a readable address for a tapped point, a driver's location or a photo's coordinates.
  </Card>
  <Card icon={<BorderAllIcon />} title="Boundaries">
    Find which city, region or country a point belongs to.
  </Card>
  <Card icon={<RulerHorizontalIcon />} title="Distances">
    Geocode two places, then pass the coordinates to the [Directions](/direction) or
    [Matrix](/matrix) API.
  </Card>
</Cards>

## Feature types

Results can be any of these feature types, from largest to smallest:

| Type           | What it covers                                              |
| -------------- | ----------------------------------------------------------- |
| `country`      | Countries, such as Ethiopia.                                |
| `region`       | Top-level regions, such as Oromia or Amhara.                |
| `place`        | Cities, towns, villages and municipalities.                 |
| `locality`     | Official parts of a city, such as sub-cities and districts. |
| `neighborhood` | Informal areas and local quarters.                          |
| `street`       | Streets with one or more addresses, such as Bole Road.      |
| `address`      | A single home, business or point of interest.               |

## Response

Both directions return the same shape: the query you sent, and a list of matching features.

```json
{
  "data": {
    "query": "Bole Road",
    "results": [
      {
        "id": "forge-416190",
        "name": "Bole Road",
        "display_name": "Bole Road, Addis Ababa, Ethiopia",
        "category": "establishment",
        "location": { "lat": 9.007932, "lng": 38.765386 },
        "address": {
          "city": "Addis Ababa",
          "country": "Ethiopia",
          "country_code": "ET"
        },
        "neighborhood": "OLYMPIA"
      }
    ]
  }
}
```

| Field                  | Type     | Description                                                                                            |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `data.query`           | `string` | The search text or coordinates you sent.                                                               |
| `data.results`         | `array`  | Matching features. Forward results are sorted by relevance and distance, reverse results by proximity. |
| `id`                   | `string` | A unique ID for the feature.                                                                           |
| `name`                 | `string` | The feature's main name.                                                                               |
| `display_name`         | `string` | The full label, combining the name, city and country.                                                  |
| `category`             | `string` | What kind of place it is, such as `establishment`, `Coffee shop` or `Store`.                           |
| `location.lat`         | `number` | Latitude of the feature's center.                                                                      |
| `location.lng`         | `number` | Longitude of the feature's center.                                                                     |
| `address.city`         | `string` | City, zone or locality.                                                                                |
| `address.country`      | `string` | Country name.                                                                                          |
| `address.country_code` | `string` | Two-letter ISO country code, such as `ET`.                                                             |
| `neighborhood`         | `string` | The neighborhood the feature is in, such as `OLYMPIA`.                                                 |

## Errors

Errors come back as an `error` object. Validation errors list the problem for each parameter in `fields`.

```json
{
  "error": {
    "code": "INVALID_INPUT",
    "fields": { "limit": ["limit must be a number"] },
    "message": "validation failed",
    "status": 400
  }
}
```

| Status | `code`          | Cause                                                                                                                                              |
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | `HE00004`       | The `apiKey` parameter is missing or the key is invalid (`Invalid token!`).                                                                        |
| `400`  | `INVALID_INPUT` | A parameter is invalid. `fields` says which, for example `limit must be between 1 and 10` or `bbox must be in format minLng,minLat,maxLng,maxLat`. |
| `400`  | `INVALID_INPUT` | Reverse geocoding: `lat` or `lon` is missing or out of range (`ReverseGeocoding: loading lat/lon`).                                                |
| `5xx`  |                 | A problem on our side. Retry the request.                                                                                                          |

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).
