GET /reverse API

GET/reverse

• Geocoding

Reverse geocode a latitude/longitude pair.

Returns nearby features ordered by relevance for the supplied point. Optional filters can restrict by layer, source, radius, or country.

Parameters

Parameters

Name	In	Type	Required	Description
point.lat	query	number	Yes	Latitude of the point to reverse geocode.
point.lon	query	number	Yes	Longitude of the point to reverse geocode.
size	query	integer	No	Number of results to return. Values above 40 are coerced to 40.
boundary.circle.radius	query	number	No	Radius in kilometers for circular boundary filtering. Defaults to 50 for search and autocomplete, and 1 for reverse. Reverse queries cap the value at 5 km.
boundary.country	query	string	No	Restrict results to ISO-3166 alpha-2 or alpha-3 country codes. Provide a comma separated list for multiple countries.
boundary.gid	query	string	No	Pelias global identifier used to restrict results to a parent geography.
sources	query	array	No	Comma separated list of data sources to include.
layers	query	array	No	Comma separated list of record layers to include in the response.

• point.latqueryRequired
  Typenumber

  Latitude of the point to reverse geocode.

• point.lonqueryRequired
  Typenumber

  Longitude of the point to reverse geocode.

• sizequeryOptional
  Typeinteger

  Number of results to return. Values above 40 are coerced to 40.

• boundary.circle.radiusqueryOptional
  Typenumber

  Radius in kilometers for circular boundary filtering. Defaults to 50 for search and autocomplete, and 1 for reverse. Reverse queries cap the value at 5 km.

• boundary.countryqueryOptional
  Typestring

  Restrict results to ISO-3166 alpha-2 or alpha-3 country codes. Provide a comma separated list for multiple countries.

• boundary.gidqueryOptional
  Typestring

  Pelias global identifier used to restrict results to a parent geography.

• sourcesqueryOptional
  Typearray

  Comma separated list of data sources to include.

• layersqueryOptional
  Typearray

  Comma separated list of record layers to include in the response.

Sample responses

Sample responses

• 200 Success — Successful reverse geocoding response.

  application/json → GeoJSONFeatureCollection

  Nearby results

  {
    "type": "FeatureCollection",
    "geocoding": {
      "version": "1.0.0",
      "timestamp": "2024-03-18T12:35:10Z",
      "engine": {
        "name": "pelias",
        "author": "geobridge",
        "version": "2.14.0"
      },
      "query": {
        "point.lat": 48.858268,
        "point.lon": 2.294471,
        "size": 3
      }
    },
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            2.294481,
            48.85837
          ]
        },
        "properties": {
          "id": "5013364",
          "gid": "openstreetmap:venue:way/5013364",
          "layer": "venue",
          "source": "openstreetmap",
          "source_id": "way/5013364",
          "name": "Tour Eiffel",
          "label": "Tour Eiffel, Paris 7e Arrondissement, Île-de-France, France",
          "confidence": 0.99,
          "accuracy": "point",
          "distance": 0,
          "continent": "Europe",
          "country": "France",
          "country_a": "FRA",
          "region": "Île-de-France",
          "county": "Paris",
          "locality": "Paris",
          "neighbourhood": "Gros-Caillou",
          "postalcode": "75007"
        }
      }
    ]
  }

  Nearby features around the supplied coordinates.

• 400 Client error — Invalid input parameters supplied.

  application/json → GeoJSONFeatureCollection

  Invalid latitude

  {
    "type": "FeatureCollection",
    "geocoding": {
      "version": "1.0.0",
      "timestamp": "2024-03-18T12:35:10Z",
      "query": {
        "point.lat": 132,
        "point.lon": 2.294471
      },
      "errors": [
        {
          "code": "INVALID_COORDINATES",
          "message": "point.lat must be a value between -90 and 90."
        }
      ]
    },
    "features": []
  }

  Latitude outside the permitted range.

• 408 Client error — Upstream search engine timeout.

  application/json → GeoJSONFeatureCollection

  Reverse timeout

  {
    "type": "FeatureCollection",
    "geocoding": {
      "version": "1.0.0",
      "query": {
        "point.lat": 48.858268,
        "point.lon": 2.294471
      },
      "errors": [
        {
          "code": "TIMEOUT",
          "message": "Reverse lookup exceeded the 1500 ms timeout window."
        }
      ],
      "warnings": [
        {
          "code": "RETRY_REQUEST",
          "message": "Retry with a smaller radius or after a short delay."
        }
      ]
    },
    "features": []
  }

  Timeout from the reverse geocoding engine.

• 500 Server error — Unexpected server error.

  application/json → GeoJSONFeatureCollection

  Reverse server error

  {
    "type": "FeatureCollection",
    "geocoding": {
      "version": "1.0.0",
      "query": {
        "point.lat": 48.858268,
        "point.lon": 2.294471
      },
      "errors": [
        {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "Unexpected exception calling the reverse index."
        }
      ]
    },
    "features": []
  }

  Example of an unexpected backend failure.

Code samples

Code samples

200 OK

cURL

# 200 OK — Looks up addresses near the Eiffel Tower using a narrow radius.
curl -s -G 'https://api-na.geobridge.io/v1/reverse' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'point.lat=48.858268' \
  --data-urlencode 'point.lon=2.294471' \
  --data-urlencode 'size=3' \
  --data-urlencode 'layers=address'

Node.js

// 200 OK — Looks up addresses near the Eiffel Tower using a narrow radius.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "point.lat": "48.858268",
  "point.lon": "2.294471",
  "size": "3",
  "layers": "address"
});
const requestUrl = `https://api-na.geobridge.io/v1/reverse` + `?${params.toString()}`;
const response = await fetch(requestUrl, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  },
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

Python

# 200 OK — Looks up addresses near the Eiffel Tower using a narrow radius.
import requests

url = 'https://api-na.geobridge.io/v1/reverse'
params = {
  "point.lat": "48.858268",
  "point.lon": "2.294471",
  "size": "3",
  "layers": "address"
}
headers = {
  "X-API-Key": "YOUR_API_KEY"
}
payload = None
response = requests.get(url, params=params, headers=headers, timeout=10)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

Go

// 200 OK — Looks up addresses near the Eiffel Tower using a narrow radius.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/reverse")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("point.lat", "48.858268")
  q.Set("point.lon", "2.294471")
  q.Set("size", "3")
  q.Set("layers", "address")
  u.RawQuery = q.Encode()
  req, err := http.NewRequest(http.MethodGet, u.String(), nil)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

Java

// 200 OK — Looks up addresses near the Eiffel Tower using a narrow radius.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/reverse?point.lat=48.858268&point.lon=2.294471&size=3&layers=address"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

C#

// 200 OK — Looks up addresses near the Eiffel Tower using a narrow radius.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/reverse?point.lat=48.858268&point.lon=2.294471&size=3&layers=address");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

400 Bad Request

cURL

# 400 Bad Request — Uses an out-of-range latitude to illustrate validation failures.
curl -s -G 'https://api-na.geobridge.io/v1/reverse' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'point.lat=123.456' \
  --data-urlencode 'point.lon=2.294471'

Node.js

// 400 Bad Request — Uses an out-of-range latitude to illustrate validation failures.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "point.lat": "123.456",
  "point.lon": "2.294471"
});
const requestUrl = `https://api-na.geobridge.io/v1/reverse` + `?${params.toString()}`;
const response = await fetch(requestUrl, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  },
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

Python

# 400 Bad Request — Uses an out-of-range latitude to illustrate validation failures.
import requests

url = 'https://api-na.geobridge.io/v1/reverse'
params = {
  "point.lat": "123.456",
  "point.lon": "2.294471"
}
headers = {
  "X-API-Key": "YOUR_API_KEY"
}
payload = None
response = requests.get(url, params=params, headers=headers, timeout=10)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

Go

// 400 Bad Request — Uses an out-of-range latitude to illustrate validation failures.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/reverse")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("point.lat", "123.456")
  q.Set("point.lon", "2.294471")
  u.RawQuery = q.Encode()
  req, err := http.NewRequest(http.MethodGet, u.String(), nil)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

Java

// 400 Bad Request — Uses an out-of-range latitude to illustrate validation failures.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/reverse?point.lat=123.456&point.lon=2.294471"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

C#

// 400 Bad Request — Uses an out-of-range latitude to illustrate validation failures.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/reverse?point.lat=123.456&point.lon=2.294471");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

408 Request Timeout

cURL

# 408 Request Timeout — Handle timeouts when reverse geocoding under load.
curl -s -G 'https://api-na.geobridge.io/v1/reverse' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'point.lat=48.858268' \
  --data-urlencode 'point.lon=2.294471'

Node.js

// 408 Request Timeout — Handle timeouts when reverse geocoding under load.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "point.lat": "48.858268",
  "point.lon": "2.294471"
});
const requestUrl = `https://api-na.geobridge.io/v1/reverse` + `?${params.toString()}`;
const response = await fetch(requestUrl, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  },
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

Python

# 408 Request Timeout — Handle timeouts when reverse geocoding under load.
import requests

url = 'https://api-na.geobridge.io/v1/reverse'
params = {
  "point.lat": "48.858268",
  "point.lon": "2.294471"
}
headers = {
  "X-API-Key": "YOUR_API_KEY"
}
payload = None
response = requests.get(url, params=params, headers=headers, timeout=10)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

Go

// 408 Request Timeout — Handle timeouts when reverse geocoding under load.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/reverse")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("point.lat", "48.858268")
  q.Set("point.lon", "2.294471")
  u.RawQuery = q.Encode()
  req, err := http.NewRequest(http.MethodGet, u.String(), nil)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

Java

// 408 Request Timeout — Handle timeouts when reverse geocoding under load.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/reverse?point.lat=48.858268&point.lon=2.294471"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

C#

// 408 Request Timeout — Handle timeouts when reverse geocoding under load.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/reverse?point.lat=48.858268&point.lon=2.294471");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

500 Internal Server Error

cURL

# 500 Internal Server Error — Demonstrates graceful degradation if reverse geocoding fails server-side.
curl -s -G 'https://api-na.geobridge.io/v1/reverse' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'point.lat=48.858268' \
  --data-urlencode 'point.lon=2.294471'

Node.js

// 500 Internal Server Error — Demonstrates graceful degradation if reverse geocoding fails server-side.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "point.lat": "48.858268",
  "point.lon": "2.294471"
});
const requestUrl = `https://api-na.geobridge.io/v1/reverse` + `?${params.toString()}`;
const response = await fetch(requestUrl, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  },
  signal: AbortSignal.timeout(10000)
});
console.log(response.status);
const payload = await response.text();
console.log(payload);

Python

# 500 Internal Server Error — Demonstrates graceful degradation if reverse geocoding fails server-side.
import requests

url = 'https://api-na.geobridge.io/v1/reverse'
params = {
  "point.lat": "48.858268",
  "point.lon": "2.294471"
}
headers = {
  "X-API-Key": "YOUR_API_KEY"
}
payload = None
response = requests.get(url, params=params, headers=headers, timeout=10)
print(response.status_code)

try:
    print(response.json())
except ValueError:
    print(response.text)

Go

// 500 Internal Server Error — Demonstrates graceful degradation if reverse geocoding fails server-side.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
  "net/url"
  "time"
)

func main() {
  client := &http.Client{Timeout: 10 * time.Second}
  u, err := url.Parse("https://api-na.geobridge.io/v1/reverse")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("point.lat", "48.858268")
  q.Set("point.lon", "2.294471")
  u.RawQuery = q.Encode()
  req, err := http.NewRequest(http.MethodGet, u.String(), nil)
  if err != nil {
    log.Fatal(err)
  }
  req.Header.Set("Accept", "application/json")
  req.Header.Set("X-API-Key", "YOUR_API_KEY")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  fmt.Println(resp.StatusCode)
  payload, _ := io.ReadAll(resp.Body)
  fmt.Println(string(payload))
}

Java

// 500 Internal Server Error — Demonstrates graceful degradation if reverse geocoding fails server-side.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(10))
        .build();

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api-na.geobridge.io/v1/reverse?point.lat=48.858268&point.lon=2.294471"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .timeout(Duration.ofSeconds(10))
        .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}

C#

// 500 Internal Server Error — Demonstrates graceful degradation if reverse geocoding fails server-side.
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient();
        using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api-na.geobridge.io/v1/reverse?point.lat=48.858268&point.lon=2.294471");
        request.Headers.Add("Accept", "application/json");
        request.Headers.Add("X-API-Key", "YOUR_API_KEY");
        var response = await client.SendAsync(request);
        Console.WriteLine((int)response.StatusCode);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Try it live

Try it live

Save your API key once and reuse it across endpoints. Configure the request below and send it directly from the docs.

API key

Clear

Stored locally in your browser. Removing it clears access for this device.

Serverhttps://api.geobridge.io/v1

Query parameters

point.lat*

Latitude of the point to reverse geocode.

point.lon*

Longitude of the point to reverse geocode.

size

Number of results to return. Values above 40 are coerced to 40.

boundary.circle.radius

Radius in kilometers for circular boundary filtering. Defaults to 50 for search and autocomplete, and 1 for reverse. Reverse queries cap the value at 5 km.

boundary.country

Restrict results to ISO-3166 alpha-2 or alpha-3 country codes. Provide a comma separated list for multiple countries.

boundary.gid

Pelias global identifier used to restrict results to a parent geography.

sources

Comma separated list of data sources to include.

layers

Comma separated list of record layers to include in the response.

Send request Reset

Configure the request and select “Send request” to preview the response.

—