Geocoding

Geocoding turns an address or place name into coordinates, and reverse geocoding turns coordinates back into an address. Use it for address forms that fill themselves in, store locators, delivery zones, and readable labels for a dropped pin or GPS fix.

Both endpoints use the places scope and cost one request each, from the shared free allowance first.

Find an address

GET /v1/search finds addresses and places that match free text.

Request

curl "https://api.mapricot.com/v1/search?q=128+SW+3rd+Ave,+Portland&limit=1" \
  -H "Authorization: Bearer $MAPRICOT_KEY"

Response

{  "attribution": [    {      "source": "openaddresses",      "text": "OpenAddresses",      "url": "https://openaddresses.io"    }  ],  "results": [    {      "id": "mp_b3BlbmFkZHJlc3NlczphZGRyZXNzOnVzL29yL211bHRub21haDpkZjdlYzM3YWJiYTJiNWM0",      "type": "address",      "name": "128 SW 3rd Avenue",      "label": "128 SW 3rd Avenue, Portland, OR, USA",      "lat": 45.521736,      "lon": -122.673276,      "address": {        "houseNumber": "128",        "street": "SW 3rd Avenue",        "postalCode": "97204",        "locality": "Portland",        "region": "Oregon",        "regionCode": "OR",        "country": "United States",        "countryCode": "US"      },      "source": "openaddresses"    }  ]}

Parameter	Description
`q`	The text to search for, 1 to 500 characters
`focus`	Optional `lat,lon` that ranks results near that point higher
`country`	Optional list of up to 10 ISO country codes, comma separated, such as `US,CA`
`limit`	Optional number of results, 1 to 20
`lang`	Optional ISO 639-1 language for names and labels, such as `fr`; defaults to `en`, so the Eiffel Tower is labelled "Eiffel Tower" rather than "Tour Eiffel"

To suggest addresses while someone types, use /v1/autocomplete with the same parameters.

Find the address at a point

GET /v1/reverse returns the nearest address or street to a coordinate. Where there is no address nearby, it returns the surrounding town, county, region, or country instead. It never returns businesses; use nearby search for those.

Request

curl "https://api.mapricot.com/v1/reverse?lat=45.5217&lon=-122.6733&limit=1" \
  -H "Authorization: Bearer $MAPRICOT_KEY"

Response

{  "attribution": [    {      "source": "openaddresses",      "text": "OpenAddresses",      "url": "https://openaddresses.io"    }  ],  "results": [    {      "id": "mp_b3BlbmFkZHJlc3NlczphZGRyZXNzOnVzL29yL211bHRub21haDpkZjdlYzM3YWJiYTJiNWM0",      "type": "address",      "name": "128 SW 3rd Avenue",      "label": "128 SW 3rd Avenue, Portland, OR, USA",      "lat": 45.521736,      "lon": -122.673276,      "address": {        "houseNumber": "128",        "street": "SW 3rd Avenue",        "postalCode": "97204",        "locality": "Portland",        "region": "Oregon",        "regionCode": "OR",        "country": "United States",        "countryCode": "US"      },      "distanceMeters": 4,      "source": "openaddresses"    }  ]}

Each result includes distanceMeters from the point you sent.

Results

Every result has a type, such as address, street, locality, region, or country, so you can tell an exact address from a town-level match. Fields the source doesn't have, such as a postal code, are left out rather than guessed.

Each result has a Mapricot ID you can store and look up later with /v1/places/{id}.

Data and attribution

Addresses and places come from OpenAddresses, OpenStreetMap, Overture, Who's On First, and GeoNames. Each response lists the credits for the sources in its results under attribution. If your app displays results, show those credits.

See the API reference for errors and limits.