Skip to content
looot docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Turn an address into coordinates

Run job:maps.geocode.forward through the looot API: 1 provider, from $0.000167 per call. Inputs, prices, output shape and code for curl, JavaScript and Python.

Turn an address into coordinates.

Job id maps.geocode.forward, in Maps & local (Maps & local). As of 2026-10-01, 1 provider serve it through 1 tool. Run job:maps.geocode.forward and looot picks one of them; with fallback on, a miss moves on to the next. See Jobs.

Inputs

This job has one tool, so it takes that tool’s fields. Any key you send passes through unchanged.

Name Type Required Description
abbrv integer no 1 or 0 (OpenCage’s actual wire format; its OpenAPI spec declares this as boolean but the live API rejects true/false and expects an integer).
add_request integer no 1 or 0 (OpenCage’s actual wire format; its OpenAPI spec declares this as boolean but the live API rejects true/false and expects an integer).
address_only integer no 1 or 0 (OpenCage’s actual wire format; its OpenAPI spec declares this as boolean but the live API rejects true/false and expects an integer).
bounds string no decimal coordinates in min long, min lat, max long, max lat order. Example: “-0.563160,51.280430,0.278970,51.683979”
countrycode string no Example: “de”
language string no the preferred language of results. Example: “de”
limit integer no Example: 1
no_annotations integer no 1 or 0 (OpenCage’s actual wire format; its OpenAPI spec declares this as boolean but the live API rejects true/false and expects an integer).
no_dedupe integer no 1 or 0 (OpenCage’s actual wire format; its OpenAPI spec declares this as boolean but the live API rejects true/false and expects an integer).
no_record integer no 1 or 0 (OpenCage’s actual wire format; its OpenAPI spec declares this as boolean but the live API rejects true/false and expects an integer).
pretty integer no 1 or 0 (OpenCage’s actual wire format; its OpenAPI spec declares this as boolean but the live API rejects true/false and expects an integer).
proximity string no Latitude and longitude decimal coordinates to bias results toward. Example: “52.3877830, 9.7334394”
q string yes Location to geocode - can be an address, place name, or decimal coordinates in latitude, longitude order. Example: “52.5432379, 13.4142133”
roadinfo integer no 1 or 0 (OpenCage’s actual wire format; its OpenAPI spec declares this as boolean but the live API rejects true/false and expects an integer).

Providers and prices

Provider Tool Price
OpenCage opencage-json $0.000167 per call

A call that fails at the provider costs $0. See What’s free.

Output

Shape of the run’s result, checked against 5 real answers:

{ rate: { limit, reset, remaining }, status: { code, message }, thanks, results: { bounds: { northeast: { ... }, southwest: { ... } }, geometry: { lat, lng }, formatted, components: Record<string, str... ...

The shape is cut here. Signed in, looot inspect opencage-json prints all of it.

Run it

Every call needs your API token in LOOOT_TOKEN; Sign in shows how to get one. Each run also needs a new idempotency key, so a retry never pays twice. With wait: 30 the answer comes back inline when the run ends within 30 seconds. Otherwise you get the running run back: poll GET /v1/runs/<runId>.

Example input with placeholder values:

curl -X POST "https://api.looot.ai/v1/runs" \
  -H "Authorization: Bearer $LOOOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"endpointId":"job:maps.geocode.forward","input":{"q":"52.5432379, 13.4142133","limit":1,"bounds":"-0.563160,51.280430,0.278970,51.683979","language":"de","proximity":"52.3877830, 9.7334394","countrycode":"de"},"wait":30}'
const response = await fetch("https://api.looot.ai/v1/runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOOOT_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    endpointId: "job:maps.geocode.forward",
    input: {
      q: "52.5432379, 13.4142133",
      limit: 1,
      bounds: "-0.563160,51.280430,0.278970,51.683979",
      language: "de",
      proximity: "52.3877830, 9.7334394",
      countrycode: "de",
    },
    wait: 30,
  }),
});
const run = await response.json();
console.log(run.status, run.result);
import os
import uuid

import requests

response = requests.post(
    "https://api.looot.ai/v1/runs",
    headers={
        "Authorization": f"Bearer {os.environ['LOOOT_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "endpointId": "job:maps.geocode.forward",
        "input": {
            "q": "52.5432379, 13.4142133",
            "limit": 1,
            "bounds": "-0.563160,51.280430,0.278970,51.683979",
            "language": "de",
            "proximity": "52.3877830, 9.7334394",
            "countrycode": "de",
        },
        "wait": 30,
    },
    timeout=90,
)
run = response.json()
print(run["status"], run.get("result"))

To pin one provider, send its tool id as endpointId instead of job:maps.geocode.forward.

Was this page helpful?