sfoln/geocode-address · Developer tools, Automation, Travel On request
Geocode addresses to coordinates and reverse-geocode coordinates to addresses worldwide: formatted address, latitude/longitude, confidence, address parts, timezone, currency and calling code. US street addresses add Census tract, county and congressional district. $0.80 per 1,000 lookups.
Geocoding API – Address to Coordinates converts addresses to coordinates and coordinates to addresses, worldwide, in bulk. Each result is one clean record with the formatted address, latitude/longitude, a confidence score, structured components (country, state, city, postcode, road, house number) and useful extras: timezone and UTC offset, currency, calling code, flag, driving side and an OpenStreetMap link. US street addresses are matched by the US Census Bureau geocoder and also get their Census geographies (tract, block, county FIPS, congressional and state legislative districts, ZIP code area, metro area) at no extra cost. Mix both directions in one list: anything that looks like lat,lng is reverse-geocoded. Built for CRM and lead enrichment, logistics, analytics, store locators and AI agents.
Price
Price per delivered record
Event
Price
Per 1,000
Charged for
Geocoded address address-geocoded
$0.0008
$0.80 / 1,000
Charged once per address or coordinate pair looked up: a US Census match, an OpenCage result, or an OpenCage lookup with no match (OpenCage counts those too).
Apify free plan: up to 10 items per run. Paid plans have no per-run cap; set maxTotalChargeUsd to cap spend.
Run
Call it from code, an agent or the Console
This API is private on Apify for now. Email us and we will publish it for you, usually within two working days. The calls below work once it is public. contact@sfoln.com
POST https://api.apify.com/v2/actors/sfoln~geocode-address/runs?maxTotalChargeUsd=1
GET https://api.apify.com/v2/actor-runs/{runId} # until status is SUCCEEDED
GET https://api.apify.com/v2/datasets/{defaultDatasetId}/items?format=json
Authenticate with an Apify API token. MCP clients can instead sign in with OAuth when prompted. Example prompt for an agent: Geocode "Brandenburger Tor, Berlin" and "350 Fifth Avenue, New York" and give me their coordinates and time zones.
Input
Input fields
List addresses (forward geocoding) or "lat,lng" pairs (reverse geocoding), one per line.
Field
Type
Default
Meaning
queries *
array
required
Addresses or coordinates Addresses or place names (forward), or "latitude,longitude" pairs such as "52.5163,13.3777" (reverse; latitude first), one per line. Max 500 characters per line. Accounts on the Apify free plan can process up to 10 addresses per run.
countryCode
string
—
Country hint Restrict forward results to these countries: ISO 3166-1 alpha-2 code(s), comma separated, e.g. "us" or "de,at,ch". Strongly recommended for short or ambiguous addresses. With "us" every street address goes to the US Census geocoder first.
language
string
—
Language Language for the formatted address and components, e.g. "en", "de", or "native" for the local language. Default: English where available.
useCensusForUs
boolean
true
Use the US Census geocoder for US addresses US street addresses are geocoded by the free US Census Bureau geocoder first (adds censusGeographies: tract, county, congressional district …); addresses it cannot match fall back to OpenCage. Off = OpenCage for every input.
maxItems
integer
1000
Max items Safety cap on how many addresses are processed in this run. Range 1–100000.
concurrency
integer
2
Concurrency Parallel requests (1–5). The geocoder limits requests per second, so more workers mostly add rate-limit errors. Range 1–5.
includeRaw
boolean
false
Include raw upstream response Attach the unmodified upstream response to each record (OpenCage's answer, or { census } for US Census matches; larger output).
Records land in the run's dataset; a synchronous call returns them directly. Each has a status (ok is charged; everything else is free) and a charged flag. The run's OUTPUT record totals items and charges.
Field
Type
Meaning
input
string | object
Input The input item this record corresponds to.
status
string
Status ok | not_found | error | skipped_invalid | skipped_budget | skipped_free_plan
charged
boolean
Charged Whether the record's main event was charged.
chargedEvent
string | null
Charged event Event charged by the runner for this record, if any.
source
string
Source Which geocoder answered: census (US Census Bureau geocoder, US street addresses) or opencage (everything else).
fetchedAt
string
Fetched at ISO timestamp.
warnings
array | null
Warnings Non-fatal problems (pages not reachable, truncation, budget limits).
error
object | null
Error { code, message, provider?, status? } when status is not ok.
query
string | null
Query The address or "lat,lng" pair as provided.
mode
string | null
Mode forward (address → coordinates) or reverse (coordinates → address).
formatted
string | null
Formatted address Full formatted address of the best match.
latitude
number | null
Latitude WGS84 latitude.
longitude
number | null
Longitude WGS84 longitude.
confidence
integer | null
Confidence OpenCage confidence 0–10 (10 = within ~250 m bounding box, 1 = > 25 km, 0 = unknown); US Census matches are street-address points (10).
type
string | null
Result type Kind of match: building, road, city, postcode, county, state, country ... (Census matches: building).
components
object | null
Components { country, countryCode, state, city, postcode, road, houseNumber } (city falls back to town / village / municipality).
timezone
string | null
Timezone IANA timezone, e.g. Europe/Berlin.
utcOffset
string | null
UTC offset Current UTC offset, e.g. +0200.
currency
string | null
Currency ISO 4217 currency code of the location.
callingCode
integer | null
Calling code International dialling code.
flag
string | null
Flag Country flag emoji.
driveOn
string | null
Drives on left | right.
speedUnit
string | null
Speed unit kmh | mph.
mapUrl
string | null
Map URL OpenStreetMap link to the location.
attribution
string | null
Attribution Data source of the result (OpenCage / OpenStreetMap contributors, or the US Census Bureau geocoder).
matchType
string | null
Match type Census matches: exact (agrees with every part of the input) or non_exact (the Census corrected part of the address, e.g. the ZIP code); null for OpenCage.
censusGeographies
object | null
Census geographies US Census matches: state, county, tract, blockGroup, block, congressionalDistrict, stateLegislativeDistrictUpper/Lower, place, countySubdivision, zcta, cbsa, csa, metropolitanDivision, schoolDistrict, urbanArea, puma, region, division. Null for OpenCage results.
candidates
array | null
Candidates Census ambiguous_address records (OpenCage not configured): the matching addresses { formatted, latitude, longitude }.
found
boolean | null
Found false on not_found records.
raw
object | null
Raw Unmodified upstream response (includeRaw): OpenCage's answer, or { census } for US Census matches.
US street addresses go to the US Census Bureau geocoder first (free, and it adds the Census tract, county and congressional district); every other address, coordinates and the US addresses the Census cannot match go to OpenCage (OpenStreetMap data). Each record says which one in its source field.
Why is a US address in upper case?
Census results use the standardized USPS form of the address ("1600 PENNSYLVANIA AVE NW"). Turn off useCensusForUs to get OpenCage's formatting for every input.