Products
Localities
Features
Localities Geocoding API

May 19, 2022

Localities Geocoding API

Convert addresses, postal codes, and localities to geographic coordinates, and vice versa. Use this API for geocoding, reverse geocoding, and batch address processing in your applications.

What is the Geocoding API?
When to Use This API
API Endpoint
Request Parameters
Implementation Options
API Request Examples
Understanding the Response
Response Examples
Usage Limits & Quotas
Working Code Examples
Related Features

Complete API Specification: Geocoding API Reference

What is the Geocoding API?

The Geocoding API converts complete address text strings into geographic coordinates (forward geocoding) and coordinates into human-readable addresses (reverse geocoding). Unlike 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 API

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 Autocomplete + Details is for. If you need to find points of interest around a location, use Nearby instead.

Address and postal code geocoding may require specific product activation. See Address Coverage for details.

API Endpoint

        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.

        # Forward geocoding - Client-side
?address=224+Rue+de+Rivoli+Paris&key=YOUR_PUBLIC_KEY

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

# Reverse geocoding
?latlng=48.879017,2.331382&private_key=YOUR_PRIVATE_KEY

For complete authentication details and security best practices, see API Keys Documentation.

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 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 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 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 for supported languages and regional availability.

Complete Parameter Reference

For all available parameters, data types, constraints, and advanced options, see the OpenAPI Specification.

Implementation Options

Choose the best integration approach for your project. See the Integration Path Guide for detailed comparison of REST API, Widget, JS SDK, Map JS API, and Store Locator options.

API Request Examples

Forward Geocoding

        # 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

        # 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

Localities Geocode call

URL

cURL

JavaScript

NodeJS

Python

Java

Ruby

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

            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'

    

            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));

    

            const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/localities/geocode?address=Place%20Jeanne-d\'Arc&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);
});


    

            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)


    

            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();

    

            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

The API returns an array of results sorted by relevance. For complete response schema, see the OpenAPI Specification.

Key Response Fields

formatted_address - Human-readable complete address

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

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

        "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 for the complete matrix.

Response Examples

            {
  "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 for implementation details (includes both forward and reverse geocoding).

Alternative Solutions:

Autocomplete API + Details API - Interactive address search with user selection
Nearby API - Find points of interest around coordinates

‹ Details Nearby ›

Was this article helpful?

Have more questions? Submit a request