# Geocoding API — Address & Coordinate Lookup (`khadinakbar/geocoding-api-byok`) Actor

OpenCage geocoding for forward addresses and reverse coordinates. Returns normalized addresses, coordinates, components, confidence, and timezone metadata for $0.006 per response.

- **URL**: https://apify.com/khadinakbar/geocoding-api-byok.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Developer tools, MCP servers, Agents
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 opencage geocoding responses

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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](https://opencagedata.com/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](https://mcp.apify.com) 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

```json
{
  "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`.

```json
{
  "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

```bash
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.

# Actor input Schema

## `openCageApiKey` (type: `string`):

Required caller-owned OpenCage API key. This secret is used only for the provider request and is never persisted or logged.

## `addresses` (type: `array`):

Street addresses or place descriptions to convert into coordinates. Each non-empty value creates one OpenCage request.

## `coordinates` (type: `array`):

Latitude and longitude pairs to convert into normalized addresses, formatted as latitude,longitude. Each pair creates one OpenCage request.

## `language` (type: `string`):

Optional IETF language tag for localized address labels, such as en, fr, or de.

## `countryCode` (type: `string`):

Optional two-letter ISO country code that limits forward-geocode candidates, such as us, gb, or pk. It is ignored for reverse geocoding.

## `maxRequests` (type: `integer`):

Maximum combined address and coordinate lookups to send in one run. The default is 25 and the hard maximum is 100.

## `maxRunCostUsd` (type: `number`):

Optional cap for Actor response-event charges, excluding Apify platform usage and your separate OpenCage bill. For example, 0.06 permits up to ten $0.006 responses.

## Actor input object example

```json
{
  "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": 25,
  "maxRunCostUsd": 0.06
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset items with input, normalized candidates, coordinates, confidence, components, and fetch timestamps.

## `summary` (type: `string`):

Compact OUTPUT terminal record with outcome, item count, event charges, and warnings.

## `runSummary` (type: `string`):

Detailed RUN\_SUMMARY terminal record with request counts, response diagnostics, and privacy flag.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "addresses": [
        "1600 Amphitheatre Parkway, Mountain View, CA"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/geocoding-api-byok").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "addresses": ["1600 Amphitheatre Parkway, Mountain View, CA"] }

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/geocoding-api-byok").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "addresses": [
    "1600 Amphitheatre Parkway, Mountain View, CA"
  ]
}' |
apify call khadinakbar/geocoding-api-byok --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/geocoding-api-byok"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/t4UoVrX5CdPY6iEgw/builds/PxjmPfZSQNcSCZM6i/openapi.json