Best Practices
These recommendations are specific to integrating AmbaLay Maps services in production.
Use the smallest allowed service set
Only enable the allowed services your application needs. This reduces accidental use of unrelated endpoints and keeps keys easier to reason about.
Prefer header authentication when possible
Use x-ambalay-key for backend, mobile, and server-to-server integrations.
Use ?key= only when the client cannot attach headers easily, such as browser-based tile rendering.
Handle responses by envelope, not by assumptions
Always parse these fields:
statusmessagerequestIddata
Do not assume a request succeeded only because it returned JSON. Check status first.
Treat quota errors differently from transient failures
Do not retry SERVICE_LIMIT_EXCEEDED automatically. The integration should pause requests for that service and prompt the user to review available usage.
For network or temporary server failures, use bounded retries with backoff.
Cache stable lookups when appropriate
Repeated geocoding and reverse geocoding requests for the same inputs should be cached in your application when your product rules allow it.
This reduces latency and avoids unnecessary quota usage.
Keep tiles and JSON services separate in your client design
Tile requests return binary PBF vector tile data. JSON services such as geocoding, route, matrix, and trips return the standard response envelope.
Your client code should parse them differently.
Log request IDs for troubleshooting
When a service request fails, capture the returned requestId. This makes support and incident follow-up much faster.