Build with location.

Start without a production server

Use the developer sandbox after signing in and accepting IP-security consent. Create a seven-day tz_test_ credential and call GET /sandbox/v1/reverse from your laptop. No static-IP approval or payment is required for this evaluation environment.

curl 'https://locationiq.co.tz/sandbox/v1/reverse?latitude=-6.81&longitude=39.28' \
  -H 'X-API-Key: YOUR_SANDBOX_KEY'

100 requests per account per Tanzania calendar day, 20/minute, and a shared 500-request daily public-network safety cap. Rotating a key revokes the previous credential and does not reset limits. The response contains bounded location context; bulk exports, routing and catchments are not included. Missing values remain unavailable. Actual observations and estimates stay separate.

Download Python, Node.js and PHP starters. Set LOCATIONIQ_KEY in your environment, then run python locationiq.py, node locationiq.mjs or php locationiq.php. Read the included README. Never ship a key in a browser bundle or URL.

Move to production

Create a scoped tz_live_ key, submit the fixed outbound IP of your server and wait for administrator approval. Set LOCATIONIQ_ENV=production and replace the sandbox key. The endpoint becomes /v1/reverse. Credentials cannot cross environments. Public map evaluation separately allows 10 lookups per public network each day; it resets at midnight Africa/Nairobi.

Your first location request

Location IQ connects coordinates with Tanzania’s administrative areas, named places and spatial insights. Explore a result in the workspace, then integrate the same service through a scoped API key.

1. Open the workspace and register or sign in. Accept the IP security policy to enable authenticated services.
2. Open API keys, choose a name, expiry and required scopes, then copy the key. Its full value is shown when created.
3. Send the key in the X-API-Key header. Keep it in your server environment, outside browser bundles and source control.

curl 'https://locationiq.co.tz/v1/reverse?latitude=-6.816&longitude=39.28' \
  -H 'X-API-Key: YOUR_API_KEY'

Find exact parameters and response schemas in the interactive API reference or OpenAPI schema. The playground generates a request using your selected fields.

Accounts, consent and scoped keys

Account and billing actions use your signed-in browser session. Spatial requests accept X-API-Key or Authorization: Bearer YOUR_API_KEY. Your account and key must be active, the key must be unexpired, and the required scopes must be present. Never put a key in a URL.

Catchment jobs need areas and landmarks; driving also needs roads. See each endpoint’s contract for its exact requirements.

Create a key with POST /account/keys, list keys with GET /account/keys, and revoke one with DELETE /account/keys/{id}. These actions require your session.

Registration requires a password of 12–128 characters and accept_ip: true. Existing accounts can accept the current policy with POST /account/consent. Read the privacy and IP consent policy. Email verification and general password reset are not currently provided.

Choose a query with a purpose

GET /v1/nearest?latitude=-6.816&longitude=39.28&category=health&limit=5&radius_m=5000

Use category values from GET /v1/catalog. A valid request can return an empty list or null administrative fields when coverage is absent. Preserve nulls instead of guessing names. Review overlaps and ambiguous matches before selecting a place.

One API key. One approved server IP.

Enter the public static outbound IPv4 or IPv6 of your application server in API keys. API calls are enabled only after administrator approval. Pending, rejected, disabled or unsubmitted addresses cannot use a key. Replacing the IP pauses access until review. Your signed-in dashboard remains available.

Keep keys on your server. Behind NAT, submit the fixed public outbound address. IPv4 and IPv6 are distinct; use the approved network family. IP approval does not certify a static address or distinguish physical servers sharing NAT.

PUT /account/keys/{key_id}/server-ip
{"ip_address":"YOUR_PUBLIC_STATIC_IP"}

HTTP 403 SERVER_IP_NOT_APPROVED means approval is required. SERVER_IP_MISMATCH means the calling server has a different outbound address. Only one exact public IP is allowed; hostnames, CIDR ranges, ports, private and multicast addresses are rejected. Approval and disabling are reviewed and audited in the admin portal.

Assign and interpret Location IQ addresses

Open Geocoding in the workspace to find a location on the map, assign an address from coordinates or interpret a shared code. Overview also shows the Geocoding address of your selected location.

curl 'https://locationiq.co.tz/v1/geocoding/encode?latitude=-6.81&longitude=39.28' \
  -H 'X-API-Key: YOUR_API_KEY'

curl 'https://locationiq.co.tz/v1/geocoding/decode?address=IReXK0L' \
  -H 'X-API-Key: YOUR_API_KEY'

The example returns IReXK0L. Addresses are case-sensitive: copy letters exactly as returned. Use a key with the geocoding scope. Existing keys retain their permissions.

Responses contain the address, its location coordinates, geometry and coverage status. Add include_context=true for bounded map context. Normal usage accounting applies. Invalid or outside-coverage addresses return 422; missing sign-in/key returns 401; missing scope returns 403.

Retrieve the fields your application needs

POST /v1/query accepts a supported dataset, selected fields, filters and output options. The catalog describes each dataset’s exact field names, filters and defaults.

curl 'https://locationiq.co.tz/v1/query' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"dataset":"landmarks","filters":{"category":"health"},"fields":["id","name","longitude","latitude"],"limit":20}'

Options include search, administrative-area or bounding-box filters, pagination and JSON or GeoJSON where supported. Use the returned pagination information rather than treating the first page as the whole dataset. Spatial filters depend on the dataset.

Queries are read-only and limited to supported fields. Saved queries belong to your account and can be managed through the workspace or session-protected /account/presets routes. A saved definition is a reusable request, not a permanent result snapshot.

Calculate reach without holding a connection open

Choose straight-line radius coverage or modelled driving reach with an access corridor. Driving estimates exclude live congestion and do not guarantee a journey time.

POST /v1/catchment/jobs
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{"latitude":-6.816,"longitude":39.28,"mode":"driving",
 "travel_minutes":20,"access_buffer_m":200,"minimum_confidence":0.75}

1. A successful submission returns HTTP 202, a job ID and a status URL.
2. Poll the returned URL every 1.5–2 seconds with the same account and suitable scopes.
3. When state becomes complete, read result. When it becomes failed, display its error.
4. Save or export the completed result before temporary job records are cleaned up.

A browser can resume its saved job after a connection interruption. An identical repeat may reuse a pending or recent completed job. Job acceptance time and background calculation time are different measurements.

Polling is rate-limited but excluded from usage counting. Completed and failed jobs become eligible for deletion after 24 hours, with daily cleanup. The compatible synchronous GET /v1/catchment remains available; background jobs are preferred for driving analysis.

Official observations and estimates stay separate

Official population applies to its published geographic level and year. Village allocations, catchment population and disaggregated welfare indicators are computed estimates, not newly observed village census values.

Village population uses whole people. Parent totals reconcile with available allocations and retained uncovered residuals. Missing coverage is not zero population. Building coverage can be incomplete, and building use varies.

Regional welfare rates and consumption means inherited by villages remain planning assumptions. They do not establish household income, actual customer demand or a sales forecast. Retain the year, unit, observed/computed status and coverage when presenting values to your users.

Facility labels can be recorded names, generic types or unverified candidates. A readable label is not proof of an individually verified name. Coordinates do not imply a GPS survey or confirmed entrance. Historical traffic describes its reference period; it is not live congestion. Validate high-impact decisions with current local evidence.

Data licences and attribution apply to exports and derived products.

Follow activity and choose a plan

Usage reports request counts, successes, errors, average response time, daily activity, popular endpoints and reported response bytes. Job submission latency excludes background computation. Scope and validation failures can count as requests; job-status polling is excluded.

GET /plans lists current TZS prices and active payment methods. GET /account/billing shows your subscription, monitored allowances and private payment history.

1. Choose a plan and period, then use an administrator-published payment method.
2. Pay the exact quoted amount using those instructions.
3. Submit your transaction reference and a PNG, JPEG or PDF receipt, up to 5 MB.
4. An administrator verifies payment and approves or rejects it with a note.

Approval activates a term immediately or after an existing paid term. Annual terms last twelve calendar months; allowances are measured monthly. Plan and payment-method changes do not alter an existing quote. Receipt access is private to its owner and authorized reviewers.

Allowances are currently monitored rather than enforced. There is no automatic renewal or overage deduction. An optional per-request cost estimate is separate from verified subscription payments. Checkout stays unavailable until payment methods are published and submissions enabled.

Handle errors and interruptions

Errors use {"detail":"message"} or a validation-detail array. Do not turn an error or missing value into zero. Avoid blindly resubmitting payment writes. General spatial requests are limited to 120 per minute per key or browser account; dataset and heavy-analysis limits also apply.

X-Response-Time-Ms measures application processing, excluding client network time and browser rendering. Use bounded retries instead of duplicate heavy jobs.

Integration checklist

• Use HTTPS and store keys on your server.
• Request only needed scopes and fields.
• Handle nulls, ambiguous names, missing coverage and pagination.
• Keep official and estimated values labelled with units and years.
• Use background jobs for driving analysis and save completed results.
• Track errors and usage; revoke unused keys.
• Carry required attribution into exported or derived products.

Try the playground → · Open the API reference →