Which timeout should I choose?
Ten seconds is a conservative tutorial default, not a universal production target. Measure normal latency from each deployment region, include connection and response time, and select a bound that protects the calling request budget. Background workers can use a different timeout from interactive web requests.
Which failures can be retried?
Retry connection resets, selected timeouts, and HTTP 500 only when the operation remains useful and within a bounded attempt count. Add jitter so many workers do not retry together. Stop immediately when the request is invalid, unauthenticated, or out of known capacity.
How should fallback behavior work?
Location enrichment should often be optional. Continue with a neutral country, unset timezone, or un-enriched event when product requirements permit. Record the controlled failure for monitoring and avoid inventing geographic values. Security-sensitive workflows can route uncertain cases to review rather than silently accepting or rejecting them.
How should this be operated in production?
Track request count, status category, timeout rate, and latency percentiles by endpoint and named service. Poll GET /usage at a modest interval to compare shared account capacity with individual key consumption. Alert before remaining requests reach zero, document ownership, and maintain a fallback for optional enrichment. Avoid metrics labels containing raw addresses, credentials, or other sensitive high-cardinality values.
How should capacity and retries interact?
A Pro key can reach its configured cap while shared account capacity remains, and the account can reach its plan allowance before another key reaches its maximum. Diagnose both levels before changing traffic. HTTP 429 should suppress aggressive retries because repeated calls cannot restore capacity. Bound worker concurrency and account for traffic from staging, tests, background jobs, and browser integrations in the same monthly total.
How should problems be diagnosed step by step?
Reduce the integration to one authenticated cURL request from trusted infrastructure, using GET /ip/8.8.8.8 as the known explicit fixture. Record the HTTP status, content type, elapsed time, and safely redacted body. If that succeeds, compare the application URL, headers, proxy behavior, timeout, and JSON model. If it fails, separate authentication, validation, capacity, transport, and server categories before changing code. Check GET /usage after 429, compare exact browser Origin values after CORS failure, and confirm the deployed environment received the intended secret. Do not rotate, retry, or increase limits blindly; preserve enough controlled evidence to identify the boundary that actually failed.
How should this behavior be tested?
Create unit fixtures for successful lookup or usage data, nullable optional fields, unknown additive properties, and every relevant error status. Mock timeouts and malformed intermediary responses so the client never mistakes an HTML proxy page for valid JSON. Run a small integration test with a designated nonproduction key and 8.8.8.8, inject the secret through CI, and keep live calls out of ordinary unit-test loops.
What privacy and accuracy boundaries apply?
IP intelligence is approximate network context. It does not prove identity, residence, billing country, precise device position, or individual ownership of a network organization. Retain only the source and derived fields required for the product purpose, restrict access, define deletion, and let users correct meaningful defaults. Security, financial, legal, or physical-location decisions require additional verified evidence and appropriate professional review.
Which plan and usage limits apply?
The 7-Day Developer Key provides 1,000 evaluation requests. Free includes 10,000 monthly requests and 1 active key. Starter includes 100,000 requests, 2 active keys, and up to 5 exact CORS origins per key. Pro includes 1,000,000 requests, 5 active keys, up to 10 origins per key, and a configurable 100 to 1,000,000 cap at key creation. Active keys share the account allowance.
| Plan | Monthly requests | Active keys |
|---|---|---|
| Free | 10,000 | 1 |
| Starter | 100,000 | 2 |
| Pro | 1,000,000 | 5 |
What should happen before release?
Confirm the endpoint and response model, validate URL construction, keep the secret outside source, set timeout and status-aware retry behavior, and test the real deployment environment. Add monitoring for latency, errors, shared usage, and per-key consumption. Document the owner, purpose, expected volume, fallback, retention, and rotation procedure. Review the implementation again whenever traffic, hosting origins, plan limits, or product decisions materially change.
External references
Continue with the standards and official documentation most relevant to this guide.