GET /autocomplete API

GET/autocomplete

• Geocoding

Provide type-ahead suggestions for user-entered text.

Optimised for low-latency, prefix-matching queries. Supports the same geographic focus and filtering controls as `/search`.

Parameters

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

Sample responses

• 200 Success — Successful autocomplete response.

  application/json → GeoJSONFeatureCollection

  Berlin suggestions

  {
    "type": "FeatureCollection",
    "geocoding": {
      "version": "1.0.0",
      "timestamp": "2024-03-18T12:36:02Z",
      "engine": {
        "name": "pelias",
        "author": "geobridge",
        "version": "2.14.0"
      },
      "query": {
        "text": "hard rock",
        "size": 5,
        "focus.point.lat": 52.5,
        "focus.point.lon": 13.3
      }
    },
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            13.32787,
            52.50641
          ]
        },
        "properties": {
          "id": "8735031043",
          "gid": "openstreetmap:venue:node/8735031043",
          "layer": "venue",
          "source": "openstreetmap",
          "source_id": "node/8735031043",
          "name": "Hard Rock Cafe Berlin",
          "label": "Hard Rock Cafe Berlin, Charlottenburg-Wilmersdorf, Berlin, Germany",
          "confidence": 0.87,
          "accuracy": "point",
          "continent": "Europe",
          "country": "Germany",
          "country_a": "DEU",
          "region": "Berlin",
          "locality": "Berlin",
          "neighbourhood": "Charlottenburg"
        }
      }
    ]
  }

  Prefix suggestions around Berlin.

• 400 Client error — Invalid input parameters supplied.

  application/json → GeoJSONFeatureCollection

  Missing query

  {
    "type": "FeatureCollection",
    "geocoding": {
      "version": "1.0.0",
      "timestamp": "2024-03-18T12:36:02Z",
      "query": {},
      "errors": [
        {
          "code": "MISSING_QUERY",
          "message": "text parameter is required for autocomplete."
        }
      ]
    },
    "features": []
  }

  Missing `text` parameter for autocomplete.

• 408 Client error — Upstream search engine timeout.

  application/json → GeoJSONFeatureCollection

  Autocomplete timeout

  {
    "type": "FeatureCollection",
    "geocoding": {
      "version": "1.0.0",
      "query": {
        "text": "hard rock",
        "size": 5
      },
      "errors": [
        {
          "code": "TIMEOUT",
          "message": "Autocomplete request exceeded the 750 ms timeout."
        }
      ],
      "warnings": [
        {
          "code": "RETRY_REQUEST",
          "message": "Retry shortly or reduce the requested size."
        }
      ]
    },
    "features": []
  }

  Autocomplete timeout due to high load.

• 500 Server error — Unexpected server error.

  application/json → GeoJSONFeatureCollection

  Autocomplete error

  {
    "type": "FeatureCollection",
    "geocoding": {
      "version": "1.0.0",
      "query": {
        "text": "hard rock"
      },
      "errors": [
        {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "Unexpected error while generating suggestions."
        }
      ]
    },
    "features": []
  }

  Example payload for an autocomplete failure.

Code samples

Code samples

200 OK

cURL

# 200 OK — Type-ahead query biased around Berlin.
curl -s -G 'https://api-na.geobridge.io/v1/autocomplete' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'text=hard rock' \
  --data-urlencode 'focus.point.lat=52.5' \
  --data-urlencode 'focus.point.lon=13.3' \
  --data-urlencode 'size=5'

Node.js

// 200 OK — Type-ahead query biased around Berlin.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "text": "hard rock",
  "focus.point.lat": "52.5",
  "focus.point.lon": "13.3",
  "size": "5"
});
const requestUrl = `https://api-na.geobridge.io/v1/autocomplete` + `?${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 — Type-ahead query biased around Berlin.
import requests

url = 'https://api-na.geobridge.io/v1/autocomplete'
params = {
  "text": "hard rock",
  "focus.point.lat": "52.5",
  "focus.point.lon": "13.3",
  "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)

Go

// 200 OK — Type-ahead query biased around Berlin.
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/autocomplete")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("text", "hard rock")
  q.Set("focus.point.lat", "52.5")
  q.Set("focus.point.lon", "13.3")
  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))
}

Java

// 200 OK — Type-ahead query biased around Berlin.
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/autocomplete?text=hard+rock&focus.point.lat=52.5&focus.point.lon=13.3&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());
  }
}

C#

// 200 OK — Type-ahead query biased around Berlin.
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/autocomplete?text=hard+rock&focus.point.lat=52.5&focus.point.lon=13.3&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());
    }
}

400 Bad Request

cURL

# 400 Bad Request — Missing text parameter triggers validation error.
curl -s -G 'https://api-na.geobridge.io/v1/autocomplete' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'size=5'

Node.js

// 400 Bad Request — Missing text parameter triggers validation error.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "size": "5"
});
const requestUrl = `https://api-na.geobridge.io/v1/autocomplete` + `?${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 — Missing text parameter triggers validation error.
import requests

url = 'https://api-na.geobridge.io/v1/autocomplete'
params = {
  "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)

Go

// 400 Bad Request — Missing text parameter triggers validation error.
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/autocomplete")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  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))
}

Java

// 400 Bad Request — Missing text parameter triggers validation error.
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/autocomplete?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());
  }
}

C#

// 400 Bad Request — Missing text parameter triggers validation error.
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/autocomplete?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());
    }
}

408 Request Timeout

cURL

# 408 Request Timeout — Illustrates timeout handling for autocomplete.
curl -s -G 'https://api-na.geobridge.io/v1/autocomplete' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'text=union' \
  --data-urlencode 'size=5'

Node.js

// 408 Request Timeout — Illustrates timeout handling for autocomplete.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "text": "union",
  "size": "5"
});
const requestUrl = `https://api-na.geobridge.io/v1/autocomplete` + `?${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 — Illustrates timeout handling for autocomplete.
import requests

url = 'https://api-na.geobridge.io/v1/autocomplete'
params = {
  "text": "union",
  "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)

Go

// 408 Request Timeout — Illustrates timeout handling for autocomplete.
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/autocomplete")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("text", "union")
  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))
}

Java

// 408 Request Timeout — Illustrates timeout handling for autocomplete.
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/autocomplete?text=union&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());
  }
}

C#

// 408 Request Timeout — Illustrates timeout handling for autocomplete.
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/autocomplete?text=union&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

cURL

# 500 Internal Server Error — Handles unexpected server error responses for autocomplete.
curl -s -G 'https://api-na.geobridge.io/v1/autocomplete' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'text=union' \
  --data-urlencode 'size=5'

Node.js

// 500 Internal Server Error — Handles unexpected server error responses for autocomplete.
// Node.js 18+ with global fetch support.
const params = new URLSearchParams({
  "text": "union",
  "size": "5"
});
const requestUrl = `https://api-na.geobridge.io/v1/autocomplete` + `?${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 — Handles unexpected server error responses for autocomplete.
import requests

url = 'https://api-na.geobridge.io/v1/autocomplete'
params = {
  "text": "union",
  "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)

Go

// 500 Internal Server Error — Handles unexpected server error responses for autocomplete.
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/autocomplete")
  if err != nil {
    log.Fatal(err)
  }
  q := u.Query()
  q.Set("text", "union")
  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))
}

Java

// 500 Internal Server Error — Handles unexpected server error responses for autocomplete.
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/autocomplete?text=union&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());
  }
}

C#

// 500 Internal Server Error — Handles unexpected server error responses for autocomplete.
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/autocomplete?text=union&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

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

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.

Send request Reset

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

—