Requests and results
Submit an address, text, or coordinates and read the returned results.
Geocode requests
Submit street (house number and street) and at least one of city, state, or zip. Values are trimmed and limited to 256 bytes each. Keep ZIP codes as strings.
{
"street": "11 Wall Street",
"city": "New York",
"state": "NY",
"zip": "10005"
}
SDK geocode requests also accept country for routing.
Search requests
Submit free text as q, such as Starbucks, Los Angeles or 90210. Optional near (lat/lon) prefers nearby results, country restricts them, and limit is 1–40 (default 10).
Reverse requests
Submit numeric lat in [-90, 90] and lon in [-180, 180]. Zero is valid.
SDK reverse requests accept an optional country hint. The SDK does not determine the country from the coordinates.
All three operations support primary source exclusions.
Autocomplete and resolution
Autocomplete requires partial text q and a recognized country. It returns suggestions with labels and provider-specific IDs. Resolution takes the selected suggestion object and returns one normalized result with coordinates. Over HTTP, autocomplete returns full results and GET /v1/place?id= looks a result up again. See address autocomplete for provider routing, session tokens, and resolution controls.
Result fields
SDK results are flat objects. Names below are TypeScript/PHP; Python uses house_number / match_type, and C# uses PascalCase. Missing text values are empty strings.
| Field | Meaning |
|---|---|
id | Provider-specific result id; primary ids work with GET /v1/place |
label | Full display address |
type | address, venue, street, zip, neighborhood, borough, city, county, state, country, or empty |
houseNumber | House number |
street | Street name without the house number |
city | City, town, or township |
state | State or province code, or its name when no code is available |
zip | ZIP or postal code as a string |
country | Recognized uppercase ISO alpha-2 code, otherwise empty |
lat, lon | Coordinates as numbers |
confidence | Provider-specific score; see confidence |
matchType | Primary only: exact, interpolated, or fallback; empty for backups |
source | Reported source identifier; may be empty |
provider | primary, google, or here |
The HTTP API returns the same information as GeoJSON features; see response format. Result order is preserved. Filtering can reduce the number of results. Primary geocode results are sorted by confidence, highest first; other operations keep their ranking order. No matches is a successful empty response. SDK resolution promises one address and raises provider_error for an empty lookup.
SDKs return one provider's result set. They do not cache, merge, or reorder results across providers.
SDK response envelope
| TypeScript / PHP | Python | Meaning |
|---|---|---|
results | results | Normalized candidate list |
provider | provider | Provider supplying the returned candidates |
fallbackReason | fallback_reason | Triggering condition, or null / None |
attempts | attempts | Ordered provider attempts, errors, and skips |
providerResponse | provider_response | Entire parsed body of the selected Google/HERE response |
The raw provider body is absent from TypeScript primary responses, None in Python objects, and null in PHP and C# objects. Python/PHP omit it during serialization for primary results; C# omits it when using GeocodingClient.JsonOptions. Earlier backup response bodies are not retained in the returned envelope.
Use Python to_dict() or PHP toArray() / json_encode() for nested model serialization. See each SDK reference for types and language-specific fields.
Autocomplete uses the same envelope with suggestions instead of results. Google suggestions include sessionToken in TypeScript/PHP or session_token in Python. Resolution returns a GeocodingResult directly and has no envelope, raw provider body, or provider-chain attempt history.