Best Practices

Authentication

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

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.

Common query parameters

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

• Example: perPage=10000

Caching:

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

Normalization:

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

Request Limits:

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

Source of Truth:

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