Geocoding API — Address & Coordinate Lookup

Geocoding API — Forward & Reverse Address Lookup

This Apify Actor is built for developers and AI agents that already have a caller-owned OpenCage API key and need structured geocoding results from a bounded batch. It accepts either street addresses for forward geocoding or latitude,longitude pairs for reverse geocoding. Each input item produces one dataset record that captures the request type, original input, provider status, result count, normalized candidate data, source, privacy flag, and fetch timestamp. The outcome is a durable, record-by-record geocoding dataset plus terminal summary records in the default key-value store.

Best fit and connected workflows

This Actor fits workflows that need predictable, structured geocoding inside Apify:

• Convert place names and street addresses into coordinates, confidence, components, and timezone metadata.
• Convert coordinates into normalized addresses and related location data.
• execution geocoding tasks from the Apify API or through Apify MCP when an agent needs dataset-backed results.
• Pair address normalization with downstream enrichment, mapping, validation, or routing logic in your own workflow.

Focused standalone workflow

Geocoding API — Forward & Reverse Address Lookup is designed as a focused standalone workflow.

Practical scenario

A logistics coordinator has a spreadsheet of pickup addresses and one warehouse coordinate pair. They send the addresses in the addresses field and the warehouse location in coordinates. The returned dataset rows include requestType, input, providerStatus, resultCount, results, source, sourceRequestPrivacy, and fetchedAt. The coordinator reviews the normalized address candidates, matches each stop to a map pin, and then passes the cleaned locations into an internal dispatch system.

Input fields

Field	Type	Required	Description
openCageApiKey	string	Yes	Caller-owned OpenCage API key used for the provider request during this run.
addresses	array of string	No	Street addresses or place descriptions to forward geocode. Each non-empty value creates one request.
coordinates	array of string	No	Latitude and longitude pairs in latitude,longitude form for reverse geocoding.
language	string	No	Optional IETF language tag for localized address labels, such as en, fr, or de.
countryCode	string	No	Optional two-letter ISO country code that narrows forward-geocode candidates.
maxRequests	integer	No	Maximum combined address and coordinate lookups for one run.
maxRunCostUsd	number	No	Optional cap for Actor response-event spend, excluding Apify platform usage and the separate OpenCage bill.

Focused input example

{
  "openCageApiKey": "YOUR_SECRET_OPENCAGE_KEY",
  "addresses": [
    "10 Downing Street, London, UK",
    "1600 Amphitheatre Parkway, Mountain View, CA"
  ],
  "coordinates": [
    "40.7484405,-73.9856644"
  ],
  "language": "en",
  "countryCode": "us",
  "maxRequests": 3,
  "maxRunCostUsd": 0.06
}

Output fields

Field	Type	Description
requestType	string	Indicates whether the row came from forward or reverse geocoding.
input	string	The address or latitude,longitude pair sent to OpenCage.
providerStatus	string	Provider response status. OK indicates a valid OpenCage response.
resultCount	integer	Number of candidate locations returned by OpenCage.
results	array	Normalized geocoding candidates, including coordinates, confidence, components, timezone, and optional what3words data.
source	string	Stable provider identifier.
sourceRequestPrivacy	string	OpenCage privacy parameter used for each request.
fetchedAt	string	ISO 8601 timestamp showing when the provider response was normalized.

Illustrative dataset record

{
  "requestType": "forward",
  "input": "1600 Amphitheatre Parkway, Mountain View, CA",
  "providerStatus": "OK",
  "resultCount": 1,
  "results": [],
  "source": "OpenCage Geocoding API",
  "sourceRequestPrivacy": "no_record=1",
  "fetchedAt": "2026-08-24T10:00:00.000Z"
}

How it works

The Actor sends each provided address or coordinate pair to OpenCage using the caller-owned API key. The key is used only for the provider request in that run and is not written to dataset records, OUTPUT, RUN_SUMMARY, or logs. Each valid provider response becomes one dataset item. The default key-value store also exposes:

• OUTPUT for a compact terminal summary
• RUN_SUMMARY for request, response, charge, and privacy diagnostics

The live contract shows two charged events: an Actor start event and one geocoding response event for each persisted OpenCage response, including a truthful no-match response. Apify platform usage is billed separately and passes through to the caller.

Pricing

Geocoding API — Forward & Reverse Address Lookup uses Pay per event billing. One event is charged when the Actor starts after valid input and a caller-provided OpenCage key are confirmed, and one event is charged for each persisted geocoding response. Apify platform usage is separate from Actor event charges, and your OpenCage account is billed separately by OpenCage.

For example, a run with three geocoding responses creates three response events plus the start event. For current pricing details and any platform usage considerations, see the live Pricing tab.

Use with AI agents (MCP)

This Actor is available as an Apify Actor usable through Apify MCP. It is useful when an agent needs a geocoding tool that returns dataset-backed, provenance-preserving records rather than a conversational guess.

Actor identity: khadinakbar/geocoding-api-byok

Tool behavior in agent workflows:

• Accepts forward geocoding inputs in addresses.
• Accepts reverse geocoding inputs in coordinates.
• Returns one dataset row per successful provider response.
• Preserves provenance with source, sourceRequestPrivacy, and fetchedAt.
• Supports bounded runs with maxRequests and maxRunCostUsd.

Geocode the following address list with my caller-owned OpenCage key: "10 Downing Street, London, UK" and "1600 Amphitheatre Parkway, Mountain View, CA". Return the normalized candidates, coordinates, confidence, components, timezone metadata, source, and fetch timestamp for each request. Use the dataset as the source of truth and summarize each row by input.

Output interpretation:

• requestType tells you whether the row is forward or reverse lookup.
• resultCount tells you how many candidate locations came back for that input.
• results contains the normalized provider candidates.
• sourceRequestPrivacy shows the privacy flag sent with every request.
• fetchedAt indicates when the response was normalized into the dataset.

Scope and cost guidance:

• One address or coordinate pair creates one provider request.
• Each persisted OpenCage response corresponds to one geocoding response event.
• maxRequests and maxRunCostUsd help bound Actor-side work and spending.
• The OpenCage bill remains separate from Apify event charges and Apify platform usage.

Apify API example

const { ApifyClient } = require('apify-client');

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

(async () => {
  const run = await client.actor('khadinakbar/geocoding-api-byok').call({
    openCageApiKey: process.env.OPENCAGE_API_KEY,
    addresses: ['10 Downing Street, London, UK'],
    maxRequests: 1,
  });

  const dataset = await client.dataset(run.defaultDatasetId).listItems();
  console.log(dataset.items);
})();

Best results and outcome guidance

Use clean, fully formed addresses for forward geocoding and latitude,longitude pairs for reverse geocoding. Keep batches within maxRequests and set maxRunCostUsd when you want a spending boundary for Actor event charges. Use countryCode only for forward geocoding, and set language when you want localized address labels in the provider response. Review the returned resultCount and results together so you can distinguish between a single strong candidate and multiple candidates for the same input.

Focused standalone workflow

Geocoding API — Forward & Reverse Address Lookup is designed as a focused standalone workflow for the public input and structured output contract described above.

Design note

I found that the live dataset contract requires requestType, input, providerStatus, resultCount, results, source, sourceRequestPrivacy, and fetchedAt on every row, which makes the output easy to interpret as one normalized response per request.

FAQ

Can I use this Actor for both forward and reverse geocoding in one run?

Yes. You can provide addresses in addresses and coordinate pairs in coordinates, and the Actor processes both types in the same run.

Does the country filter apply to reverse geocoding?

No. The countryCode field is defined for forward-geocode candidate filtering, and the contract says it is ignored for reverse geocoding.

What should I look at first in the dataset?

Start with requestType, input, providerStatus, and resultCount. Then inspect results for the normalized candidates and fetchedAt for the response timestamp.

Where do I find the terminal run summary?

Check the default key-value store records OUTPUT and RUN_SUMMARY. The output schema points to both records.

How do I connect this Actor to an agent workflow?

Use Apify MCP with the Actor identity khadinakbar/geocoding-api-byok, supply the caller-owned OpenCage key through the Actor input, and read the dataset items as the authoritative result set.

Responsible use

Use this Actor with a caller-owned OpenCage API key and keep geocoding requests scoped to data you are authorized to process. The Actor sends no_record=1 with each provider request, and the secret key is only used for the provider request in that run.