GET /search API

Search globally for places, addresses, and administrative areas.

Performs a Pelias-compatible forward geocoding request using free-form text and optional geographic filters to prioritise or constrain matches.

Parameters

Name	In	Type	Required	Description
`text`	query	string	Yes	Free-form text to geocode.
`size`	query	integer	No	Number of results to return. Values above 40 are coerced to 40.
`focus.point.lat`	query	number	No	Latitude used to bias results toward a focus point.
`focus.point.lon`	query	number	No	Longitude used to bias results toward a focus point.
`boundary.rect.min_lat`	query	number	No	Southern latitude of the rectangular bounding box.
`boundary.rect.min_lon`	query	number	No	Western longitude of the rectangular bounding box.
`boundary.rect.max_lat`	query	number	No	Northern latitude of the rectangular bounding box.
`boundary.rect.max_lon`	query	number	No	Eastern longitude of the rectangular bounding box.
`boundary.circle.lat`	query	number	No	Latitude for the center of the circular boundary filter.
`boundary.circle.lon`	query	number	No	Longitude for the center of the circular boundary filter.
`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.

textqueryRequired
Typestring
Free-form text to geocode.
sizequeryOptional
Typeinteger
Number of results to return. Values above 40 are coerced to 40.
focus.point.latqueryOptional
Typenumber
Latitude used to bias results toward a focus point.
focus.point.lonqueryOptional
Typenumber
Longitude used to bias results toward a focus point.
boundary.rect.min_latqueryOptional
Typenumber
Southern latitude of the rectangular bounding box.
boundary.rect.min_lonqueryOptional
Typenumber
Western longitude of the rectangular bounding box.
boundary.rect.max_latqueryOptional
Typenumber
Northern latitude of the rectangular bounding box.
boundary.rect.max_lonqueryOptional
Typenumber
Eastern longitude of the rectangular bounding box.
boundary.circle.latqueryOptional
Typenumber
Latitude for the center of the circular boundary filter.
boundary.circle.lonqueryOptional
Typenumber
Longitude for the center of the circular boundary filter.
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

200 Success — Successful geocoding response.
application/json → GeoJSONFeatureCollection
Successful search
{ "type": "FeatureCollection", "geocoding": { "version": "1.0.0", "timestamp": "2024-03-18T12:34:56Z", "engine": { "name": "pelias", "author": "geobridge", "version": "2.14.0" }, "query": { "text": "Union Square", "size": 5, "sources": [ "openstreetmap" ], "focus.point.lat": 40.7359, "focus.point.lon": -73.9911 } }, "features": [ { "type": "Feature", "geometry": { "type": "Point", "coordinates": [ -73.991069, 40.735863 ] }, "properties": { "id": "57182421", "gid": "openstreetmap:venue:node/57182421", "layer": "venue", "source": "openstreetmap", "source_id": "node/57182421", "name": "Union Square Park", "label": "Union Square Park, Manhattan, New York, United States", "confidence": 0.94, "accuracy": "point", "continent": "North America", "country": "United States", "country_a": "USA", "region": "New York", "county": "New York County", "locality": "New York", "neighbourhood": "Union Square", "postalcode": "10003", "categories": [ "park", "landmark" ] } } ] }
Forward geocoding with multiple matches.

400 Client error — Invalid input parameters supplied.

application/json → GeoJSONFeatureCollection

Size too large

{
  "type": "FeatureCollection",
  "geocoding": {
    "version": "1.0.0",
    "timestamp": "2024-03-18T12:34:56Z",
    "query": {
      "text": "Union Square",
      "size": 100
    },
    "errors": [
      {
        "code": "SIZE_TOO_LARGE",
        "message": "size must be between 1 and 40."
      }
    ]
  },
  "features": []
}

Page size above allowed maximum.

408 Client error — Upstream search engine timeout.

application/json → GeoJSONFeatureCollection

Search timeout

{
  "type": "FeatureCollection",
  "geocoding": {
    "version": "1.0.0",
    "query": {
      "text": "Union Square",
      "size": 5
    },
    "errors": [
      {
        "code": "TIMEOUT",
        "message": "Search backend exceeded the 1500 ms timeout."
      }
    ],
    "warnings": [
      {
        "code": "RETRY_REQUEST",
        "message": "Retry with a smaller bounding box or later."
      }
    ]
  },
  "features": []
}

Upstream search timeout.

500 Server error — Unexpected server error.

application/json → GeoJSONFeatureCollection

Server error

{
  "type": "FeatureCollection",
  "geocoding": {
    "version": "1.0.0",
    "query": {
      "text": "Union Square"
    },
    "errors": [
      {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "Unexpected exception querying the Pelias index."
      }
    ]
  },
  "features": []
}

Unexpected server error payload.

Code samples

200 OK

# 200 OK — Successful forward geocoding lookup using text and size parameters.
curl -s -G 'https://api-na.geobridge.io/v1/search' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'text=Union Square' \
  --data-urlencode 'size=5' \
  --data-urlencode 'focus.point.lat=40.7359' \
  --data-urlencode 'focus.point.lon=-73.9911'

// 200 OK — Successful forward geocoding lookup using text and size parameters.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "text": "Union Square",
  "size": "5",
  "focus.point.lat": "40.7359",
  "focus.point.lon": "-73.9911"
});
const requestUrl = `https://api-na.geobridge.io/v1/search` + `?${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);

# 200 OK — Successful forward geocoding lookup using text and size parameters.
import requests

url = 'https://api-na.geobridge.io/v1/search'
params = {
  "text": "Union Square",
  "size": "5",
  "focus.point.lat": "40.7359",
  "focus.point.lon": "-73.9911"
}
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)

// 200 OK — Successful forward geocoding lookup using text and size parameters.
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/search")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("text", "Union Square")
  q.Set("size", "5")
  q.Set("focus.point.lat", "40.7359")
  q.Set("focus.point.lon", "-73.9911")
  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))
}

// 200 OK — Successful forward geocoding lookup using text and size parameters.
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/search?text=Union+Square&size=5&focus.point.lat=40.7359&focus.point.lon=-73.9911"))
        .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());
  }
}

// 200 OK — Successful forward geocoding lookup using text and size parameters.
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/search?text=Union+Square&size=5&focus.point.lat=40.7359&focus.point.lon=-73.9911");
        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

# 400 Bad Request — Requests a page size above the maximum of 40 to trigger validation errors.
curl -s -G 'https://api-na.geobridge.io/v1/search' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'text=Union Square' \
  --data-urlencode 'size=100'

// 400 Bad Request — Requests a page size above the maximum of 40 to trigger validation errors.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "text": "Union Square",
  "size": "100"
});
const requestUrl = `https://api-na.geobridge.io/v1/search` + `?${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);

# 400 Bad Request — Requests a page size above the maximum of 40 to trigger validation errors.
import requests

url = 'https://api-na.geobridge.io/v1/search'
params = {
  "text": "Union Square",
  "size": "100"
}
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)

// 400 Bad Request — Requests a page size above the maximum of 40 to trigger validation errors.
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/search")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("text", "Union Square")
  q.Set("size", "100")
  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))
}

// 400 Bad Request — Requests a page size above the maximum of 40 to trigger validation errors.
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/search?text=Union+Square&size=100"))
        .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());
  }
}

// 400 Bad Request — Requests a page size above the maximum of 40 to trigger validation errors.
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/search?text=Union+Square&size=100");
        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

# 408 Request Timeout — Demonstrates retry-friendly pattern when the upstream search cluster times out.
curl -s -G 'https://api-na.geobridge.io/v1/search' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'text=Union Square' \
  --data-urlencode 'size=5'

// 408 Request Timeout — Demonstrates retry-friendly pattern when the upstream search cluster times out.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "text": "Union Square",
  "size": "5"
});
const requestUrl = `https://api-na.geobridge.io/v1/search` + `?${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);

# 408 Request Timeout — Demonstrates retry-friendly pattern when the upstream search cluster times out.
import requests

url = 'https://api-na.geobridge.io/v1/search'
params = {
  "text": "Union Square",
  "size": "5"
}
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)

// 408 Request Timeout — Demonstrates retry-friendly pattern when the upstream search cluster times out.
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/search")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("text", "Union Square")
  q.Set("size", "5")
  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))
}

// 408 Request Timeout — Demonstrates retry-friendly pattern when the upstream search cluster times out.
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/search?text=Union+Square&size=5"))
        .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());
  }
}

// 408 Request Timeout — Demonstrates retry-friendly pattern when the upstream search cluster times out.
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/search?text=Union+Square&size=5");
        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

# 500 Internal Server Error — Shows defensive handling for transient server errors during forward geocoding.
curl -s -G 'https://api-na.geobridge.io/v1/search' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'text=Union Square' \
  --data-urlencode 'size=5'

// 500 Internal Server Error — Shows defensive handling for transient server errors during forward geocoding.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "text": "Union Square",
  "size": "5"
});
const requestUrl = `https://api-na.geobridge.io/v1/search` + `?${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);

# 500 Internal Server Error — Shows defensive handling for transient server errors during forward geocoding.
import requests

url = 'https://api-na.geobridge.io/v1/search'
params = {
  "text": "Union Square",
  "size": "5"
}
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)

// 500 Internal Server Error — Shows defensive handling for transient server errors during forward geocoding.
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/search")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("text", "Union Square")
  q.Set("size", "5")
  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))
}

// 500 Internal Server Error — Shows defensive handling for transient server errors during forward geocoding.
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/search?text=Union+Square&size=5"))
        .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());
  }
}

// 500 Internal Server Error — Shows defensive handling for transient server errors during forward geocoding.
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/search?text=Union+Square&size=5");
        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

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

API key

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

Server

Query parameters

text*

Free-form text to geocode.

size

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

focus.point.lat

Latitude used to bias results toward a focus point.

focus.point.lon

Longitude used to bias results toward a focus point.

boundary.rect.min_lat

Southern latitude of the rectangular bounding box.

boundary.rect.min_lon

Western longitude of the rectangular bounding box.

boundary.rect.max_lat

Northern latitude of the rectangular bounding box.

boundary.rect.max_lon

Eastern longitude of the rectangular bounding box.

boundary.circle.lat

Latitude for the center of the circular boundary filter.

boundary.circle.lon

Longitude for the center of the circular boundary filter.

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.

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

—

Response headers