Places

Places helps people find businesses, landmarks, and addresses. Suggest results as people type, list the cafés or stations around a point, and save any result to look up again later.

Every places endpoint uses the places scope and costs one request, from the shared free allowance first. A completed search counts even when it finds nothing.

Suggest as people type

GET /v1/autocomplete suggests addresses and places for partial text. Pass focus with the user's location so nearby results rank first.

Request

curl "https://api.mapricot.com/v1/autocomplete?q=stumpt&focus=45.52,-122.68&limit=1" \
  -H "Authorization: Bearer $MAPRICOT_KEY"

Response

{  "attribution": [    {      "source": "openstreetmap",      "text": "© OpenStreetMap contributors",      "url": "https://www.openstreetmap.org/copyright"    }  ],  "results": [    {      "id": "mp_b3BlbnN0cmVldG1hcDp2ZW51ZTpub2RlLzExOTg2MjI2NjYw",      "type": "venue",      "name": "Stumptown Coffee Roasters",      "label": "Stumptown Coffee Roasters, Portland, OR, USA",      "lat": 45.521399,      "lon": -122.682775,      "address": {        "houseNumber": "1140",        "street": "SW Washington Street",        "postalCode": "97205",        "locality": "Portland",        "region": "Oregon",        "regionCode": "OR",        "country": "United States",        "countryCode": "US"      },      "distanceMeters": 267,      "source": "openstreetmap"    }  ]}

It takes the same parameters as search: q, and optional focus, country, limit, and lang.

List places around a point

GET /v1/nearby lists businesses and landmarks around a coordinate, nearest first. Filter by category to find a kind of place.

Request

curl "https://api.mapricot.com/v1/nearby?lat=45.52&lon=-122.68&category=food:coffee_shop&radius=1000&limit=1" \
  -H "Authorization: Bearer $MAPRICOT_KEY"

Response

{  "attribution": [    {      "source": "openstreetmap",      "text": "© OpenStreetMap contributors",      "url": "https://www.openstreetmap.org/copyright"    }  ],  "results": [    {      "id": "mp_b3BlbnN0cmVldG1hcDp2ZW51ZTpub2RlLzYzOTAwOTQ3NTU",      "type": "venue",      "name": "Public Domain",      "label": "Public Domain, Portland, OR, USA",      "lat": 45.519965,      "lon": -122.679528,      "address": {        "houseNumber": "603",        "street": "SW Broadway",        "postalCode": "97205",        "locality": "Portland",        "region": "Oregon",        "regionCode": "OR",        "country": "United States",        "countryCode": "US"      },      "categories": [        "food",        "food:coffee_shop"      ],      "distanceMeters": 37,      "source": "openstreetmap"    }  ]}

Parameter	Description
`lat`, `lon`	The point to search around
`category`	Optional list of up to 10 categories, comma separated
`radius`	Optional search radius in meters, up to 50,000
`limit`	Optional number of results, 1 to 20
`lang`	Optional ISO 639-1 language for names and labels; defaults to `en`

Nearby results include distanceMeters. They include categories only when you pass category; no other endpoint returns categories.

Search or nearby?

Use search and autocomplete to find something by name, and nearby to find a kind of place. A search for "coffee" near Portland matches places named Coffee, such as Coffee County, Tennessee, before it matches cafés. nearby with category=food:coffee_shop returns the cafés.

Categories

A place matches when it has any of the categories you pass. Each value matches exactly, so food doesn't match a place that only has food:pizza, and a value not listed here matches nothing.

Category	More specific values
`accommodation`
`education`
`entertainment`
`finance`
`food`	`food:bagel`, `food:barbecue`, `food:bougatsa`, `food:burger`, `food:burrito`, `food:cake`, `food:casserole`, `food:chicken`, `food:coffee_shop`, `food:couscous`, `food:crepe`, `food:curry`, `food:dessert`, `food:donut`, `food:empanada`, `food:fish`, `food:fish_and_chips`, `food:fried_food`, `food:friture`, `food:gyro`, `food:ice_cream`, `food:kebab`, `food:mediterranean`, `food:noodle`, `food:pancake`, `food:pasta`, `food:pie`, `food:pizza`, `food:regional`, `food:sandwich`, `food:sausage`, `food:savory_pancakes`, `food:seafood`, `food:steak`, `food:sub`, `food:sushi`, `food:tapas`, `food:vegan`, `food:vegetarian`, `food:wings`
`food:cuisine:<name>`	`<name>` is one of `african`, `american`, `arab`, `argentinian`, `asian`, `australian`, `baiana`, `balkan`, `basque`, `bavarian`, `belarusian`, `brazilian`, `cantonese`, `capixaba`, `caribbean`, `chinese`, `croatian`, `czech`, `danish`, `french`, `gaucho`, `german`, `greek`, `hunan`, `hungarian`, `indian`, `international`, `iranian`, `italian`, `japanese`, `korean`, `kyo_ryouri`, `latin_american`, `lebanese`, `malagasy`, `mexican`, `mineira`, `okinawa_ryori`, `pakistani`, `peruvian`, `polish`, `portuguese`, `rhenish`, `russian`, `shandong`, `sichuan`, `spanish`, `thai`, `turkish`, `vietnamese`, `westphalian`
`government`	`government:military`
`health`
`industry`	`industry:agriculture`
`natural`	`natural:water`
`nightlife`
`professional`
`recreation`
`religion`
`retail`
`transport`	`transport:air`, `transport:air:aerodrome`, `transport:air:airport`, `transport:bus`, `transport:public`, `transport:rail`, `transport:sea`, `transport:station`, `transport:taxi`

Look up a saved place

GET /v1/places/{id} returns one place by its Mapricot ID.

Request

curl "https://api.mapricot.com/v1/places/mp_b3BlbnN0cmVldG1hcDp2ZW51ZTpub2RlLzExOTg2MjI2NjYw" \
  -H "Authorization: Bearer $MAPRICOT_KEY"

Response

{  "attribution": [    {      "source": "openstreetmap",      "text": "© OpenStreetMap contributors",      "url": "https://www.openstreetmap.org/copyright"    }  ],  "result": {    "id": "mp_b3BlbnN0cmVldG1hcDp2ZW51ZTpub2RlLzExOTg2MjI2NjYw",    "type": "venue",    "name": "Stumptown Coffee Roasters",    "label": "Stumptown Coffee Roasters, Portland, OR, USA",    "lat": 45.521399,    "lon": -122.682775,    "address": {      "houseNumber": "1140",      "street": "SW Washington Street",      "postalCode": "97205",      "locality": "Portland",      "region": "Oregon",      "regionCode": "OR",      "country": "United States",      "countryCode": "US"    },    "source": "openstreetmap"  }}

It returns {"result": {…}, "attribution": […]}. An ID is as stable as its source's identifier. IDs from Who's On First, GeoNames, and Overture persist across data updates, and most OpenStreetMap IDs do. If a source changes or removes a record, its ID returns 404, which isn't billed, and your app should search again.

What results include

Each result has a name or label, coordinates, a type such as venue or address, an address where the source has one, and its data source. Results don't include reviews, ratings, photos, opening hours, or contact details.

Data and attribution

Businesses and landmarks come from OpenStreetMap and Overture, and addresses and areas from OpenAddresses, Who's On First, and GeoNames. The same business can appear once from each source. If your app displays results, show the credits listed in each response's attribution.

See the API reference for errors and limits.