POIs
Points of interest (POIs) are the places and geographic features published on a destination map. A POI can be a marker, path, or polygon. Set BASE_URL as shown in the API overview before running these examples.
Marker responses can include external_id for destinations synchronized from a CRM. See CRM sync for guidance on matching records.
List map POIs
Section titled “List map POIs”GET /maps/:map_id/pois
Returns POIs for a map that have any of the requested tags. Tag IDs identify the categories and tags configured for your map; retrieve them with GET /places-of-interest/items/:map_id.
| Parameter | In | Required | Description |
|---|---|---|---|
map_id | Path | Yes | Map UUID. |
tags | Query | Yes | Comma-separated tag IDs. Spaces are ignored. |
start | Query | No | Start offset for the result window. |
end | Query | No | End offset for the result window. |
curl --get "$BASE_URL/maps/11111111-1111-4111-8111-111111111111/pois" \ --data-urlencode "tags=aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa,bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb" \ --data-urlencode "start=0" \ --data-urlencode "end=49"List markers
Section titled “List markers”GET /maps/:map_id/markers
Returns the markers on a map. You can request markers from a specific map version.
| Parameter | In | Required | Description |
|---|---|---|---|
map_id | Path | Yes | Map UUID. |
version_id | Query | No | Map-version UUID. |
curl "$BASE_URL/maps/11111111-1111-4111-8111-111111111111/markers"Get a map marker
Section titled “Get a map marker”GET /maps/:map_id/markers/:marker_id
Returns one marker and verifies that it belongs to the specified map.
| Parameter | In | Required | Description |
|---|---|---|---|
map_id | Path | Yes | Map UUID. |
marker_id | Path | Yes | Marker UUID. |
curl "$BASE_URL/maps/11111111-1111-4111-8111-111111111111/markers/55555555-5555-4555-8555-555555555555"Get a marker by ID
Section titled “Get a marker by ID”GET /markers/:marker_id
Returns one marker without requiring its map ID.
| Parameter | In | Required | Description |
|---|---|---|---|
marker_id | Path | Yes | Marker UUID. |
curl "$BASE_URL/markers/55555555-5555-4555-8555-555555555555"Categories and tags
Section titled “Categories and tags”List a map’s categories and tags
Section titled “List a map’s categories and tags”GET /places-of-interest/items/:map_id
Returns the category and tag hierarchy configured for a map. Use the item IDs from this response as tags values when listing map POIs.
| Parameter | In | Required | Description |
|---|---|---|---|
map_id | Path | Yes | Map UUID. |
sort_type | Query | No | Sort items by alphabetical, popularity, or the map’s custom order. |
version_id | Query | No | Limit tag calculations to a map-version UUID. |
include_counts | Query | No | Use true to include each item’s POI count for this map. |
curl --get "$BASE_URL/places-of-interest/items/11111111-1111-4111-8111-111111111111" \ --data-urlencode "sort_type=custom" \ --data-urlencode "include_counts=true"Get a map’s POI configuration
Section titled “Get a map’s POI configuration”GET /places-of-interest/map/:mapId
Returns a map’s markers, paths, and polygons as GeoJSON feature collections for presenting its POI categories.
| Parameter | In | Required | Description |
|---|---|---|---|
mapId | Path | Yes | Map UUID. |
version_id | Query | No | Return POIs from this map-version UUID. |
curl "$BASE_URL/places-of-interest/map/11111111-1111-4111-8111-111111111111"Get a POI by ID
Section titled “Get a POI by ID”GET /places-of-interest/id/:poiId
Resolves a marker, path, or polygon by its POI ID. The response identifies the resolved type and includes its record.
| Parameter | In | Required | Description |
|---|---|---|---|
poiId | Path | Yes | Marker, path, or polygon UUID. |
curl "$BASE_URL/places-of-interest/id/55555555-5555-4555-8555-555555555555"List POI icons
Section titled “List POI icons”GET /places-of-interest/icons
Returns the icon vocabulary available for POI categories and tags. Each icon record includes its stored fields, including its name and URL.
This endpoint has no parameters.
curl "$BASE_URL/places-of-interest/icons"Get category and POI order
Section titled “Get category and POI order”GET /places-of-interest/tags-pois-orders
Returns map-specific category ordering. Pass type=keywords for the map’s top-level categories, or pass a category path ID to return its child categories and ordered POIs.
| Parameter | In | Required | Description |
|---|---|---|---|
map_id | Query | Yes | Map UUID. |
type | Query | Conditional | Use keywords to return top-level category order. Required when path_id is omitted. |
path_id | Query | Conditional | Category path UUID. Required when type is omitted. |
curl --get "$BASE_URL/places-of-interest/tags-pois-orders" \ --data-urlencode "map_id=11111111-1111-4111-8111-111111111111" \ --data-urlencode "type=keywords"POI associations
Section titled “POI associations”Get associations for one POI
Section titled “Get associations for one POI”GET /poi-associations/:poi_id
Returns the universal associations for one POI, ordered by their configured sort order and creation time.
| Parameter | In | Required | Description |
|---|---|---|---|
poi_id | Path | Yes | Marker, path, or polygon UUID. |
curl "$BASE_URL/poi-associations/55555555-5555-4555-8555-555555555555"Get associations for multiple POIs
Section titled “Get associations for multiple POIs”GET /poi-associations
Returns associations grouped by each requested POI ID. Each association includes the associated POI’s ID, type, name, and coordinates when available.
| Parameter | In | Required | Description |
|---|---|---|---|
poi_ids | Query | Yes | Comma-separated marker, path, or polygon UUIDs. |
list_id | Query | No | Also include associations visible from this list UUID. |
include_reverse | Query | No | Use true to also return mutual associations where a requested POI is the associated POI. |
curl --get "$BASE_URL/poi-associations" \ --data-urlencode "poi_ids=55555555-5555-4555-8555-555555555555,88888888-8888-4888-8888-888888888888" \ --data-urlencode "include_reverse=true"List paths
Section titled “List paths”GET /maps/:map_id/paths
Returns the paths on a map. You can request paths from a specific map version.
| Parameter | In | Required | Description |
|---|---|---|---|
map_id | Path | Yes | Map UUID. |
version_id | Query | No | Map-version UUID. |
curl "$BASE_URL/maps/11111111-1111-4111-8111-111111111111/paths"Get a path
Section titled “Get a path”GET /maps/:map_id/paths/:path_id
Returns one path and verifies that it belongs to the specified map.
| Parameter | In | Required | Description |
|---|---|---|---|
map_id | Path | Yes | Map UUID. |
path_id | Path | Yes | Path UUID. |
curl "$BASE_URL/maps/11111111-1111-4111-8111-111111111111/paths/88888888-8888-4888-8888-888888888888"Get a path by ID
Section titled “Get a path by ID”GET /paths/:path_id
Returns one path without requiring its map ID.
| Parameter | In | Required | Description |
|---|---|---|---|
path_id | Path | Yes | Path UUID. |
curl "$BASE_URL/paths/88888888-8888-4888-8888-888888888888"Polygons
Section titled “Polygons”List polygons
Section titled “List polygons”GET /maps/:map_id/polygons
Returns the polygons on a map. You can request polygons from a specific map version.
| Parameter | In | Required | Description |
|---|---|---|---|
map_id | Path | Yes | Map UUID. |
version_id | Query | No | Map-version UUID. |
curl "$BASE_URL/maps/11111111-1111-4111-8111-111111111111/polygons"Get a polygon
Section titled “Get a polygon”GET /maps/:map_id/polygons/:polygon_id
Returns one polygon and verifies that it belongs to the specified map.
| Parameter | In | Required | Description |
|---|---|---|---|
map_id | Path | Yes | Map UUID. |
polygon_id | Path | Yes | Polygon UUID. |
curl "$BASE_URL/maps/11111111-1111-4111-8111-111111111111/polygons/99999999-9999-4999-8999-999999999999"Get a polygon by ID
Section titled “Get a polygon by ID”GET /polygons/:polygon_id
Returns one polygon without requiring its map ID.
| Parameter | In | Required | Description |
|---|---|---|---|
polygon_id | Path | Yes | Polygon UUID. |
curl "$BASE_URL/polygons/99999999-9999-4999-8999-999999999999"