Response format
GeoJSON results, address fields, result types, confidence, and empty results.
Every endpoint returns a GeoJSON FeatureCollection. Each result is a Feature with a point geometry and properties that use familiar US address names matching the request parameters (street, city, state, zip). Results are in ranked order. GeoJSON works directly with map libraries such as Leaflet, Mapbox GL, and OpenLayers; in application code, read features[i].properties.
Collection
| Field | Type | Behavior |
|---|---|---|
type | String | Always FeatureCollection |
features | Array | Results; empty when nothing matched |
bbox | Array | [minLon, minLat, maxLon, maxLat] around all results; absent when empty |
Result properties
Every result has every property below, in this order. A property is null when it does not apply or is unknown, so you can rely on the shape.
| Property | Type | Description |
|---|---|---|
id | String | Stable result id; look it up again with /v1/place |
label | String | Full display address, e.g. 11 Wall Street, New York, NY, USA |
type | String | What was matched; see result types |
name | String | Short name: 11 Wall Street for an address, Starbucks for a venue, Oakland for a city |
house_number | String or null | House number |
street | String or null | Street name, without the house number |
unit | String or null | Unit, suite, or apartment |
neighborhood | String or null | Neighborhood |
city | String or null | City, town, or township |
county | String or null | County |
state | String or null | State or province code, e.g. NY; the full name when no code exists |
state_name | String or null | Full state or province name, e.g. New York |
zip | String or null | ZIP or postal code |
country | String or null | ISO 3166-1 alpha-2 country code, e.g. US |
lat | Number | Latitude (same as geometry.coordinates[1]) |
lon | Number | Longitude (same as geometry.coordinates[0]) |
confidence | Number | Score in [0, 1]; see confidence |
match_type | String | exact, interpolated (estimated position along a street), or fallback (a less specific match, such as the street when the house number was not found) |
distance_m | Integer or null | Meters from the near point (search, autocomplete) or the query point (reverse) |
categories | Array | Venue categories such as amenity:cafe; empty for other types |
source | String | Data source, e.g. openaddresses, openstreetmap, whosonfirst |
A feature may also include a bbox when the result covers an area, such as a city.
Result types
type is one of the values below. The same names are accepted by the types parameter.
| Type | Matches |
|---|---|
address | A house number on a street |
venue | A business or point of interest |
street | A street without a house number |
zip | A ZIP or postal code area |
neighborhood | A neighborhood |
borough | A borough |
city | A city, town, or township |
county | A county |
state | A state or province |
country | A country |
Empty results
HTTP/1.1 200 OK
Content-Type: application/json
X-Geocoding-Outcome: no_match
{"type": "FeatureCollection", "features": []}
A no-match response is distinct from invalid input or service failure. A matched response has at least one result and X-Geocoding-Outcome: matched, regardless of confidence. An unknown /v1/place id returns an empty collection; SDK resolution methods raise provider_error for this because they return one address.
Confidence and order
Geocode confidence compares your street, city, state, and ZIP with each match and is lowered when different addresses match nearly equally well. It is at most 0.99 and is not a probability. Search, autocomplete, and reverse confidence come from ranking and distance and are not comparable with geocode scores.
Geocode results are sorted by confidence, highest first; ties keep ranking order. Source identifiers are not reliability ratings. See confidence details.
API and SDK differences
SDKs return flat result objects with the same information (id, label, type, house number, street, city, state, zip, country, lat, lon, confidence, match type, source) plus provider identity, attempts, fallback reasons, and optionally the selected backup's raw response. They normalize missing confidence to 0 and can return Google/HERE results with different scoring semantics.
Use this page for direct HTTP parsing. Use the SDK result guide for normalized SDK responses.