Source: https://developers.woosmap.com/products/localities/features/geocoding/

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# Localities Geocoding



**Complete API Specification** : [Geocoding Endpoint Reference](/api-reference/localities-api/get-localities-geocode/)

## What is the Geocoding Endpoint?

The Geocoding Endpoint converts complete address text strings into geographic coordinates (forward geocoding) and coordinates into human-readable addresses (reverse geocoding). Unlike [Autocomplete](/products/localities/features/autocomplete/), which returns suggestions as users type, Geocoding processes full address strings in a single request.

### What It Does

Forward geocoding takes complete or partial address text—like “224 Rue de Rivoli, Paris”—and returns matching locations with coordinates, structured address components, and accuracy indicators. Results are ranked by relevance, and you can filter by location type (address, locality, postal\_code) or restrict to specific countries.

Reverse geocoding takes coordinates—like `48.879017,2.331382`—and returns the nearest address within 200 meters. If no address exists within that radius, you get an empty result. You can also request all sub-buildings at the same location (apartments, units) using the `list_sub_buildings` parameter.

### Key Characteristics

Geocoding is designed for batch processing, data enrichment, and server-side workflows where you have complete addresses—not interactive user input. Results include accuracy indicators (`ROOFTOP`, `GEOMETRIC_CENTER`, `APPROXIMATE`) so you can assess coordinate precision. You control response completeness with the `fields` parameter to optimize both payload size and billing costs.

## When to Use This Endpoint

Use Geocoding for batch address processing, enriching existing address databases with coordinates, converting GPS locations to addresses, or processing complete addresses without user interaction. It’s perfect for backend workflows, data pipelines, mapping historical data, or converting delivery addresses from orders.

Don’t use Geocoding for interactive address search—that’s what [Localities Autocomplete](/products/localities/features/autocomplete/) + [Localities Details](/products/localities/features/details/) is for. If you need to find points of interest around a location, use [Localities Nearby](/products/localities/features/nearby/) instead.

Address and postal code geocoding may require specific product activation. See [Address Coverage](/products/localities/concepts/address-coverage/) for details.

## API Endpoint

```http
GET https://api.woosmap.com/localities/geocode
```

### Authentication

Authenticate using either a `key` (public API key for client-side requests) or `private_key` (for server-side requests). Public keys require domain/IP restrictions, while private keys should be kept secret and never exposed in client code. You can also use the `X-Api-Key` header for server-side or mobile authentication.

```shell
# Forward geocoding - Client-side (query parameter)
?address=224+Rue+de+Rivoli+Paris&key=YOUR_PUBLIC_KEY

# Forward geocoding - Server-side (query parameter)
?address=224+Rue+de+Rivoli+Paris&private_key=YOUR_PRIVATE_KEY

# Reverse geocoding (query parameter)
?latlng=48.879017,2.331382&private_key=YOUR_PRIVATE_KEY

# Server-side / Mobile (header)
-H "X-Api-Key: YOUR_PRIVATE_KEY"
```

For complete authentication details and security best practices, see [API Keys Documentation](/api-reference/authentication/).

## Request Parameters

### Required Parameters

**For Forward Geocoding (Address → Coordinates):**

**`address`** - The complete or partial address text to geocode (truncated after 150 characters, must be URL encoded).

**`key`** or **`private_key`** - Your API authentication key. See [Authentication](#authentication) above.

**For Reverse Geocoding (Coordinates → Address):**

**`latlng`** - Coordinates in `latitude,longitude` format (e.g., `48.879017,2.331382`).

**`key`** or **`private_key`** - Your API authentication key. See [Authentication](#authentication) above.

### Key Optional Parameters

**`components`** - **Strongly recommended.** Restrict results to specific countries using ISO 3166-1 codes (e.g., `country:fr` or `country:gb|country:fr|country:be`). There is no limit on the number of countries you can specify. Improves accuracy and relevance.

**`types`** - Filter result types (default: `locality|postal_code|address`). See [Locality Types](/products/localities/concepts/locality-types/) for all available types and their descriptions. Available values: `address`, `locality`, `postal_code`, `admin_level`, `country`. Use pipe (`|`) to combine multiple types.

**`language`** - Return results in a specific language where available (e.g., `fr`, `de`, `en`). See [Language Support](/products/localities/concepts/language-support/) for supported languages and regional availability.

### Complete Parameter Reference

For all available parameters, data types, constraints, and advanced options, see the [OpenAPI Specification](/api-reference/localities-api/get-localities-geocode/).

## Implementation Options

Choose the best integration approach for your project. See the [Integration Path Guide](/products/localities/guides/integration-path/) for detailed comparison of REST API, Widget, JS SDK, Map JS API, and Store Locator options.

## Request Examples

### Forward Geocoding

```shell
# Basic worldwide search
curl "https://api.woosmap.com/localities/geocode/?address=224+Rue+de+Rivoli+Paris&key=YOUR_KEY"

# With country restriction (recommended)
curl "https://api.woosmap.com/localities/geocode/?address=Place+Jeanne+d'Arc&components=country:fr&key=YOUR_KEY"

# Filter to addresses only
curl "https://api.woosmap.com/localities/geocode/?address=main+street&types=address&components=country:us&key=YOUR_KEY"
```

### Reverse Geocoding

```shell
# Basic reverse geocode
curl "https://api.woosmap.com/localities/geocode/?latlng=48.879017,2.331382&key=YOUR_KEY"

# With sub-buildings (apartments, units)
curl "https://api.woosmap.com/localities/geocode/?latlng=48.879017,2.331382&list_sub_buildings=true&key=YOUR_KEY"
```

### Multi-Language Examples

```javascript
const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d'Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
```

```shell
curl -L 'https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d%27Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'
```

```python
import requests

url = "https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d'Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY"

payload = {}
headers = {
    'Referer': 'http://localhost'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

```text
https://api.woosmap.com/localities/geocode
  ?address=Place%20Jeanne-d%27Arc
  &components=country%3AFR
  &key=YOUR_PUBLIC_API_KEY
```

```javascript
const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d

## Understanding the Response

Localities Geocoding returns an array of results sorted by relevance. For the complete response schema, see the [OpenAPI Specification](/api-reference/localities-api/get-localities-geocode/).

### Key Response Fields

**`formatted_address`** - Human-readable complete address

```json
"formatted_address": "224 Rue de Rivoli, 75001 Paris, France"
```

**`geometry`** - Coordinates, viewport, and location type (accuracy indicator)

```json
"geometry": {
  "location": {"lat": 48.863469, "lng": 2.330941},
  "location_type": "ROOFTOP"
}
```

**Location type accuracy levels:**

- `ROOFTOP` - Most precise, street address accuracy
- `RANGE_INTERPOLATED` - Approximation between precise points
- `GEOMETRIC_CENTER` - Center of a polyline or polygon
- `APPROXIMATE` - General approximation
- `POSTAL_CODE` / `DISTRICT` - Inherited from postal code or district (lower precision)

**`address_components`** - Structured address parts. Available fields vary by type.

**`types`** - Result category (e.g., `address`, `locality`, `postal_code`, `route`).

**`scores_per_components`** - Quality indicator showing match scores (0-1) for `street_name`, `postal_code`, and `locality` components. Use this to assess result quality.

### Special Response Features

**UK Not Yet Built Addresses** - Include a `status` field set to `not_yet_built`.

**Reverse Geocoding Sub-Buildings** - When `list_sub_buildings=true`, results include a `sub_buildings` array with `public_id` and `description` for each address at the location.

**Address Component Availability** - Fields depend on result type. See the [OpenAPI Specification](/api-reference/localities-api/get-localities-geocode/) for the complete matrix.

## Response Examples

```json
{
  "results":
    [
      {
        "public_id": "0+FTYd/1MsiBSxLAKq+/Fiyy+uM=",
        "types": ["address", "route"],
        "formatted_address": "Place Jeanne D'Arc, 75013, Paris",
        "address_components":
          [
            {
              "types":
                ["country", "administrative_area_level_0", "division_level_0"],
              "long_name": "France",
              "short_name": "FR",
            },
            {
              "types": ["state", "division_level_1"],
              "long_name": "Île-de-France",
              "short_name": "Île-de-France",
            },
            {
              "types":
                ["administrative_area_level_1", "county", "division_level_2"],
              "long_name": "Paris",
              "short_name": "Paris",
            },
            {
              "types": ["locality"],
              "long_name": "Paris",
              "short_name": "Paris",
            },
            {
              "types": ["postal_codes"],
              "long_name": "75013",
              "short_name": "75013",
            },
            {
              "types": ["route"],
              "long_name": "Place Jeanne D'Arc",
              "short_name": "Place Jeanne D'Arc",
            },
          ],
        "geometry":
          {
            "location": { "lat": 48.829405, "lng": 2.367944 },
            "location_type": "GEOMETRIC_CENTER",
          },
        "scores_per_components": { "street_name": 1 },
      },
    ],
}
```

## Usage Limits & Quotas

- **Rate Limit** : 50 queries per second (QPS) per project
- Exceeding limits returns `429 Too Many Requests`
- Contact support for higher quotas

## Working Code Examples

### Example: Geocoding and Reverse Geocoding

See the complete [Localities Geocode JS Sample](/js-samples/localities-geocode/) for implementation details (includes both forward and reverse geocoding).

https://demo.woosmap.com/js-samples/samples/localities-geocode/app/dist/
[](https://demo.woosmap.com/js-samples/samples/localities-geocode/highlight/highlight.html "Open in new tab with highlighted code")
Try sample 

- [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/localities-geocode/app?file=index.ts)
- [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/localities-geocode/jsfiddle)
- [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/localities-geocode)

## Related Features

**Alternative Solutions:**

- [Localities Autocomplete](/products/localities/features/autocomplete/) + [Localities Details](/products/localities/features/details/) - Interactive address search with user selection
- [Localities Nearby](/products/localities/features/nearby/) - Find points of interest around coordinatesArc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY',
  headers: { 
    'Referer': 'http://localhost'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});
```

```java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d'Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY")
  .method("GET", body)
  .addHeader("Referer", "http://localhost")
  .build();
Response response = client.newCall(request).execute();
```

```ruby
require "uri"
require "net/http"

url = URI("https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d'Arc&components=country%3AFR&key=YOUR_PUBLIC_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"

response = https.request(request)
puts response.read_body
```

## Understanding the Response

Localities Geocoding returns an array of results sorted by relevance. For the complete response schema, see the [OpenAPI Specification](/api-reference/localities-api/get-localities-geocode/).

### Key Response Fields

**`formatted_address`** - Human-readable complete address

```json
"formatted_address": "224 Rue de Rivoli, 75001 Paris, France"
```

**`geometry`** - Coordinates, viewport, and location type (accuracy indicator)

```json
"geometry": {
  "location": {"lat": 48.863469, "lng": 2.330941},
  "location_type": "ROOFTOP"
}
```

**Location type accuracy levels:**

- `ROOFTOP` - Most precise, street address accuracy
- `RANGE_INTERPOLATED` - Approximation between precise points
- `GEOMETRIC_CENTER` - Center of a polyline or polygon
- `APPROXIMATE` - General approximation
- `POSTAL_CODE` / `DISTRICT` - Inherited from postal code or district (lower precision)

**`address_components`** - Structured address parts. Available fields vary by type.

**`types`** - Result category (e.g., `address`, `locality`, `postal_code`, `route`).

**`scores_per_components`** - Quality indicator showing match scores (0-1) for `street_name`, `postal_code`, and `locality` components. Use this to assess result quality.

### Special Response Features

**UK Not Yet Built Addresses** - Include a `status` field set to `not_yet_built`.

**Reverse Geocoding Sub-Buildings** - When `list_sub_buildings=true`, results include a `sub_buildings` array with `public_id` and `description` for each address at the location.

**Address Component Availability** - Fields depend on result type. See the [OpenAPI Specification](/api-reference/localities-api/get-localities-geocode/) for the complete matrix.

## Response Examples

```json
{
  "results":
    [
      {
        "public_id": "0+FTYd/1MsiBSxLAKq+/Fiyy+uM=",
        "types": ["address", "route"],
        "formatted_address": "Place Jeanne D'Arc, 75013, Paris",
        "address_components":
          [
            {
              "types":
                ["country", "administrative_area_level_0", "division_level_0"],
              "long_name": "France",
              "short_name": "FR",
            },
            {
              "types": ["state", "division_level_1"],
              "long_name": "Île-de-France",
              "short_name": "Île-de-France",
            },
            {
              "types":
                ["administrative_area_level_1", "county", "division_level_2"],
              "long_name": "Paris",
              "short_name": "Paris",
            },
            {
              "types": ["locality"],
              "long_name": "Paris",
              "short_name": "Paris",
            },
            {
              "types": ["postal_codes"],
              "long_name": "75013",
              "short_name": "75013",
            },
            {
              "types": ["route"],
              "long_name": "Place Jeanne D'Arc",
              "short_name": "Place Jeanne D'Arc",
            },
          ],
        "geometry":
          {
            "location": { "lat": 48.829405, "lng": 2.367944 },
            "location_type": "GEOMETRIC_CENTER",
          },
        "scores_per_components": { "street_name": 1 },
      },
    ],
}
```

## Usage Limits & Quotas

- **Rate Limit** : 50 queries per second (QPS) per project
- Exceeding limits returns `429 Too Many Requests`
- Contact support for higher quotas

## Working Code Examples

### Example: Geocoding and Reverse Geocoding

See the complete [Localities Geocode JS Sample](/js-samples/localities-geocode/) for implementation details (includes both forward and reverse geocoding).

https://demo.woosmap.com/js-samples/samples/localities-geocode/app/dist/
[](https://demo.woosmap.com/js-samples/samples/localities-geocode/highlight/highlight.html "Open in new tab with highlighted code")
Try sample 

- [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/localities-geocode/app?file=index.ts)
- [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/localities-geocode/jsfiddle)
- [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/localities-geocode)

## Related Features

**Alternative Solutions:**

- [Localities Autocomplete](/products/localities/features/autocomplete/) + [Localities Details](/products/localities/features/details/) - Interactive address search with user selection
- [Localities Nearby](/products/localities/features/nearby/) - Find points of interest around coordinates