Geocoding API — OpenCage BYOK address and coordinate lookup

Convert street addresses to coordinates or latitude/longitude pairs to normalized addresses. This Actor is designed for applications and AI agents that already have an OpenCage Geocoding API key and need a bounded, structured batch result with clear terminal outcomes.

Best fit

• Forward geocode known addresses into latitude/longitude, confidence, address components, and timezone data.
• Reverse geocode known coordinates into normalized addresses.
• Run through the Apify API or Apify MCP when an agent needs durable dataset rows and an OUTPUT status record.
• Not for Google Maps data, place discovery, lead generation, routing, or a substitute for a Google Maps scraper.

Keys, privacy, and billing

You provide openCageApiKey as an Apify secret input. It is used only to call OpenCage during that run; the Actor never writes it to logs, dataset items, OUTPUT, or RUN_SUMMARY. Every provider request includes no_record=1.

• Apify charge: $0.00005 to start a configured run, plus $0.006 per persisted OpenCage response.
• Provider charge: OpenCage bills your own account under its current plan.
• Platform usage: passed through to the caller. Use maxRequests and maxRunCostUsd to bound Actor-side spending.

Quick start

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

Each address or coordinate pair makes one provider request in list order. countryCode limits only forward address lookups; maxRunCostUsd stops before the next Actor event would exceed the cap and does not limit your OpenCage bill.

Returned data

Every valid provider response produces one dataset row, including an honest no-match response with resultCount: 0.

{
  "requestType": "forward",
  "input": "1600 Amphitheatre Parkway, Mountain View, CA",
  "providerStatus": "OK",
  "resultCount": 1,
  "results": [{
    "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, United States of America",
    "location": { "lat": 37.422, "lng": -122.084 },
    "confidence": 10,
    "components": { "city": "Mountain View", "country_code": "us" }
  }],
  "source": "OpenCage Geocoding API",
  "sourceRequestPrivacy": "no_record=1"
}

The default key-value store also contains OUTPUT (compact terminal outcome) and RUN_SUMMARY (request, response, charge, and warning diagnostics). Outcomes are COMPLETE, PARTIAL, VALID_EMPTY, INVALID_INPUT, UPSTREAM_FAILED, or CONFIG_ERROR.

API and agent prompt

curl -X POST "https://api.apify.com/v2/acts/khadinakbar~geocoding-api-byok/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"openCageApiKey":"YOUR_SECRET_OPENCAGE_KEY","addresses":["10 Downing Street, London, UK"],"maxRequests":1}'

With my configured OpenCage key, geocode 10 Downing Street, London, UK. Return its normalized address, coordinates, confidence, components, source, and terminal outcome. Stop after one request.

Keep the input scoped, treat an empty candidate list as a valid answer, and keep your OpenCage key only in the secret input field—not in URLs, task definitions, datasets, or logs.