---
updatedAt: 2026-03-03T19:57:06.000Z
agentTools:
  projectIndex: https://developers.unitmap.com/llms.txt
---

# Best Practices

### Authentication

* Send your standard Engrain API key in the usual auth header required by your API gateway.

<br />

### Experimental flag headers

These endpoints are gated behind experimental flags in the demo:

* Locations endpoint: include experimental flag for locations. This resource is experimental and requires the `locations-resource` experimental flag.
* Distance Matrix endpoint: include experimental flag for distances; This resource is experimental and requires the `distances` experimental flag.

<br />

### Common query parameters

`perPage`: Increase page size to avoid pagination during ingestion/testing.

* Example: `perPage=10000`

<br />

### Caching:

Locations rarely change; cache them by unitMapId and refresh only when the map or pathfinding data updates.

<br />

### Normalization:

Ensure you use the exact field name floorId (singular) in your distance requests to avoid errors.

<br />

### Request Limits:

The API supports up to 50 combined source/target pairs per request. For larger sets, chunk your requests sequentially.

<br />

### Source of Truth:

Always use API-returned values for badges and rankings, as they are more accurate than visual map estimates.