Geocode an address
Geocode an address is a tool from Google Maps, callable through the AgentSky API as googlemap/geocode and billed per call ($0.006).
Turn an address into coordinates, or coordinates into an address.
Overview
Resolves between written addresses and geographic coordinates in both directions. Given an address it returns matching places with latitude and longitude, a normalised address, the parsed address components, and a stable place identifier. Given a coordinate pair or a place identifier it returns the addresses at or near that point. A bounding box and a region code bias results toward an area without excluding others, and a language code sets the language of the returned address text.
A status and a list of matches, each with a formatted address, its components, coordinates, a viewport, and a place id.
Input
These go in the input object of the run request.
| Field | Type | Required | Description |
|---|---|---|---|
| address | string | No | The address to locate. Required unless a coordinate pair or place id is given. |
| latlng | string | No | A `lat,lng` pair to look up in reverse. |
| place_id | string | No | A known place identifier to resolve. |
| components | string | No | Pipe-separated filters such as country or postal code. |
| region | string | No | Two-letter region code to bias results toward. |
| language | string | No | Language of the returned address text. |
Requests up to 1 MB.
Example
Use your own API key and a saved idempotency key for each new job. Replace image or media placeholders with your own publicly reachable HTTPS URLs. Keep the same key and request body when recovering a timeout.
# Set once per job; reuse this key and the identical body after a timeout.
: "${AGENTSKY_IDEMPOTENCY_KEY:?Set a unique, saved key for this job}"
curl --fail-with-body https://gateway.agentsky.dev/v1/run \
-H "authorization: Bearer $AGENTSKY_API_KEY" \
-H "content-type: application/json" \
-H "Idempotency-Key: $AGENTSKY_IDEMPOTENCY_KEY" \
-d '{"provider":"googlemap","endpoint":"geocode","input":{"address":"1600 Amphitheatre Parkway, Mountain View, CA","region":"us","language":"en"}}'
# If status is READY/RUNNING, poll GET /v1/runs/{runId} with the same API key.Pricing
$0.006 per call using your plan when signed in. Read the final customer charge from price.amount.value after the run finishes. A RUNNING response is not the final bill.