Documentation / Address, business and regional place search
Address, business and regional place search
Look up addresses, brands and places with map-focus bias. Discover OSM businesses within viewports, polygons and travel-time regions.
On this page
Find a destination or businesses within reach
GET /places/lookup accepts q (1–120 characters), paired lat/lon, limit (default 8, maximum 20), language, types, category, countrycodes and bbox. Coordinates and bbox provide a soft proximity bias. Only bounded=true makes bbox a restriction. Bounds use west,south,east,north; split areas crossing the date line. Types is a comma-separated list of address,business,landmark,street,place; countrycodes contains two-letter country codes. Categories include coffee, restaurants, pharmacy, groceries, hotels, bars, shops and parks. Records without a source country code cannot satisfy a country-code filter.
Search supports partial names, accent normalization, common street abbreviations and typo matching. An explicit qualifier, such as Starbucks in Portland, overrides the current focus. Requested house numbers must match exactly; missing or different numbers are not substituted. Global name/address search uses a local Photon index. When that index is unavailable, coverage.mode is regional: the local place-name index resolves populated places and Overpass searches an area within 0.12 degrees of the supplied focus or resolved location. That fallback is not exhaustive global geocoding. The route does not call public Nominatim or public Photon.
POST /places/discover lists mapped businesses/POIs using local Overpass data. Supply exactly one region: bbox, Polygon/MultiPolygon GeoJSON (including Feature/FeatureCollection), an owned polygon result handle, or minutes with lat/lon. Polygon holes are excluded; membership is based on a node coordinate or way/relation center, not intersection of full geometry. Optional q and category filter names and POI types.
Set rankBy to travel_time to compare travel times from lat/lon, using costing auto, bicycle, pedestrian or truck. The matrix compares at most the 25 nearest candidates; it is not a global fastest-destination optimization. Unreachable candidates retain null travel times. Without travel-time ranking, results are ordered by straight-line distance from lat/lon or the region center.
Existing place-name search, autocomplete, nearby, reverse and object-lookup routes remain available. /places/search and /places/autocomplete cover populated places, not a global business catalog. Nearby and reverse lookup read OSM features around a coordinate.
# Address lookup with the current map focus as a bias.
curl --fail-with-body --get https://api.mapsource.io/places/lookup \
-H "Authorization: Bearer $MAPSOURCE_API_KEY" \
--data-urlencode 'q=720 SW Broadway, Portland' \
--data-urlencode 'lat=45.52' --data-urlencode 'lon=-122.68' \
--data-urlencode 'limit=8'
# Brand search: an explicit place qualifier overrides proximity bias.
curl --fail-with-body --get https://api.mapsource.io/places/lookup \
-H "Authorization: Bearer $MAPSOURCE_API_KEY" \
--data-urlencode 'q=Starbucks in Portland' \
--data-urlencode 'lat=47.6062' --data-urlencode 'lon=-122.3321'
# Mapped cafés in a viewport. bbox order: west,south,east,north.
curl --fail-with-body https://api.mapsource.io/places/discover \
-H "Authorization: Bearer $MAPSOURCE_API_KEY" -H 'Content-Type: application/json' \
--data '{"bbox":[-122.69,45.51,-122.67,45.53],"category":"coffee","limit":20,"offset":0}'
# Cafés within a 15-minute walk, ranked by measured travel time.
curl --fail-with-body https://api.mapsource.io/places/discover \
-H "Authorization: Bearer $MAPSOURCE_API_KEY" -H 'Content-Type: application/json' \
--data '{"lat":45.52,"lon":-122.68,"minutes":15,"costing":"pedestrian","category":"coffee","rankBy":"travel_time","limit":8}'
# Reverse lookup is a separate operation.
curl --fail-with-body \
'https://api.mapsource.io/places/reverse?lat=45.52&lon=-122.68' \
-H "Authorization: Bearer $MAPSOURCE_API_KEY"Endpoints and parameters
Select an endpoint for its full parameter and response reference.
| Operation | Endpoint |
|---|---|
| Look up addresses, businesses and places | GET /api/places/lookup |
| Find businesses and POIs in a region | POST /api/places/discover |
| Reverse geocode a coordinate | GET /api/places/reverse |
| Find features within a radius | GET /api/places/nearby |
| Read one feature by its OSM identity | GET /api/places/{osmType}/{osmId} |
| Resolve a place name to a coordinate | GET /api/places/search |
| Prefix-match a place name | GET /api/places/autocomplete |
| Resolve a name to a geographic entity | GET /api/entities/resolve |
| Geocode through the compatibility provider | GET /api/geocode |
Application integration
Use lookupPlaces for addresses, businesses, brands and destination suggestions. Pass the current map/GPS focus as a soft bias. Keep string OSM IDs and source-provided address fields; ask the user to select a result when ambiguous is true or bestMatchId is null.
Use discoverPlaces for mapped businesses inside a viewport, polygon or travel-time region. Follow pagination.nextOffset and narrow the region if coverage.truncated is true. Generated isochrones and travel-time ranking use the navigation service.
Every plan includes both search operations with the existing subscription key and shared allowance. Lookup counts one request plus any regional interpreter call; discovery counts its Overpass query and optional isochrone/matrix calls. See /docs/limits#search-accounting for examples.
Debounce typed searches, cancel superseded requests and retain returned dataset timestamps. The compatibility geocoder remains available for existing clients; it is not required for local lookup.
Access and limits
Regional discovery bounds are at most one degree per axis. Generated travel-time regions accept 1–30 minutes. At most 2,000 OSM candidates are evaluated; coverage.truncated=true means the candidate pool is incomplete and the area should be narrowed. Page size is 1–100 with offset 0–2,000. Follow pagination.nextOffset until null. Travel-time ranking requires limit <=25 and offset=0. Polygon rings must be closed; encoded coordinates are limited to 100 KB. Results can change between pages as OSM updates arrive.
Lookup consumes one request plus an interpreter request if regional fallback is used. Discovery consumes the normal requests for its Overpass query and optional isochrone/matrix; it adds no separate request charge. Existing plan rate, concurrency and response limits apply. For search-as-you-type, debounce, cancel superseded requests and respect Retry-After. Keep the service key in the application backend.
Nearby radii are 10–5,000 meters; reverse lookup supports up to 1,000 meters. The existing /geocode compatibility route uses its separately configured upstream provider; use /places/lookup for local address and business search.
See plan limits for request allowances and error handling for quota and retry behavior.
Responses and examples
Lookup returns schema mapsource-lookup.v1, query, results, bestMatchId, ambiguous, warnings and coverage. IDs are strings, including every sources[].id. Coordinates are in coordinate.lat/lon; optional bbox uses west,south,east,north. Missing address fields and geometry remain absent. match.score is a ranking value, not a probability. If bestMatchId is null or ambiguous is true, request a user selection instead of choosing a destination.
Discovery returns schema mapsource-discovery.v1, lookup-format results, region, pagination, coverage, ranking and source metadata. Each record includes travelTimeSeconds, null unless measured. Empty results mean no matches in the evaluated data, not proof that no business exists. OSM is community-maintained and not an exhaustive real-world directory. Check coverage and source timestamps before treating results as complete or current.
Example responses and timing measurements · Current service status
Attribution
Records come from OpenStreetMap under ODbL. Display © OpenStreetMap contributors and keep the source links with any record you store.
Questions about this guide? Contact support.