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.
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.