Get started

Authentication

Create an API key in the dashboard. The full key is shown only once. Store a secret key in your server’s environment, not in source control or browser code. For web pages, use a browser key restricted to your origins.

Send the key in a header

All six endpoints accept x-api-key. POST requests also need Content-Type: application/json.

x-api-key: YOUR_API_KEY
Content-Type: application/json

You can instead use a Bearer token with the same key:

Authorization: Bearer YOUR_API_KEY

Do not send both headers. If both are present, x-api-key takes precedence.

Keep secret keys private

Never include a secret key in public bundles or apps. In web pages, use a browser key restricted to your origins; proxy mobile app requests through your server. Production requests must use HTTPS.

Revoke a compromised key in the dashboard and create a replacement. Revocation takes effect within the next key sync, normally 5 seconds.

Keys are accepted only in headers, including for GET requests. A key in the URL is ignored, so the request fails with 401.

Browser keys

Libraries such as MapLibre GL Geocoder and leaflet-control-geocoder call the API directly from the page. Give them a browser key: in the dashboard, choose Browser key and list the origins of your site, one per line. An origin is https://host with an optional port, without a path. https://*.example.com covers every subdomain of example.com, but not example.com itself. Plain HTTP is only allowed for http://localhost and http://127.0.0.1, on any port. A key can have up to 20 origins, and you can edit them later.

A browser key only works when the request’s Origin header matches one of its origins, and only over JSON, not gRPC. Otherwise the API returns 403 (permission_denied). Matching replies carry Access-Control-Allow-Origin, so the browser lets your page read them. Secret keys still work from a page but get no CORS headers, so browsers block their replies.

// In your page, with a browser key restricted to this site's origin.
const response = await fetch('https://api.opengeocoding.com/v1/autocomplete', {
  method: 'POST',
  headers: {
    'x-api-key': 'og_YOUR_BROWSER_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ text: input.value, limit: 5 })
});
const { suggestions = [] } = await response.json();

A browser key is public: anyone can read it from your page, and clients outside a browser can send any Origin header. The origin list stops other websites from using it in their visitors’ browsers, not determined abuse. Every key shares your account’s per-second limit and credits, and there is no overage, so the worst case is that your account runs out of credits, never a surprise bill. Autocomplete spends no credits. If a browser key is abused, revoke it and create a new one.

Authentication failures

A missing, invalid, expired or revoked key returns HTTP 401 with code unauthenticated. These requests do not spend credits.