Usage Guide
❗ Please read this section carefully.
API behavior & Error handling
The GeoAPI enforces request throttling.
If you receive HTTP 429 Too Many Requests, pause and retry after a reasonable interval to prevent excessive rate limiting.
Also try to avoid excessive request bursts.
❗ Your integration has to be resilient to the HTTP 429 errors!
While some API endpoints can handle large batches, we recommend batching conservatively.
5 to 10 items per request is an ideal middle ground for most use cases.
Very large batches may be accepted today but could be restricted in the future.
Each error includes a description intended to help resolve the issue.
Read the descriptions carefully - they often point directly to the cause.
The API uses standard HTTP status codes:
- 2xx - Success
- 4xx/5xx - Error
- 429 - Too many requests (back off and retry)
For the actual error object format, refer to the OpenAPI/Swagger documentation.
API security requirements
To achieve the highest possible security guarantees, the API TLS layer is routinely updated to comply with the latest AWS TLS policies.
Keep your TLS libraries updated, and ensure they are never more than 5 years old!
You are required to keep your system TLS libraries up to date to support the latest AWS TLS policies at all times.
If your system does not support the required TLS ciphers, it will not be able to establish a (secure) connection to the API!
You can find the latest AWS TLS policies and supported ciphers here: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/secure-connections-supported-viewer-protocols-ciphers.html
Best practices for performance
- Batch requests: Prefer medium-sized batches (5–10 items).
- Total workload <50 items: You can send each item in a separate request without issues.
- Total workload ≥50 items: Split into multiple requests of 5–10 items each. Space requests to avoid bursts.
- Control concurrency: Limit parallel requests and avoid sending bursts. Sequence calls when possible.
- Retry with backoff: On transient errors or HTTP 429, retry after a delay that increases with each attempt if possible.
- Tracking efficiency: Poll at reasonable intervals and slow polling when no updates are expected.