What does a valid request contain?
A request combines the https://api.iprout.com base URL, one supported path, and either an Authorization Bearer token or X-API-Key header. Lookup operations use GET and do not require a JSON request body. Keep URL construction and secret injection separate so an address can never overwrite headers or other request configuration.
What does a success response contain?
Lookup success responses contain the resolved IP and available geographic and network fields. The usage endpoint returns account totals and an api_keys array instead. Use the endpoint-specific schema, check content type, and model optional location fields as nullable rather than substituting inaccurate values.
How should compatibility be maintained?
Treat new response properties as additive. Parse only the fields your product needs, preserve numeric types for coordinates and counts, and avoid positional or string-splitting logic. A generated client can start from the OpenAPI contract, but its timeout, retry, secret storage, and nullable-field behavior still require review.
How should the API contract be implemented?
Keep the production base URL and supported paths centralized in one client module. Inject authentication from trusted configuration, use a structured URL builder, set a finite timeout, and branch on HTTP status before decoding endpoint-specific JSON. Model documented optional values as nullable and ignore additive properties that the application does not need. This keeps lookup and usage behavior predictable while allowing the public response contract to evolve compatibly.
Which failures must the client handle?
Handle HTTP 401 as a credential problem, HTTP 422 as invalid explicit address input, HTTP 429 as a key-cap or shared-capacity state, and HTTP 500 or transport failure as potentially transient. Do not retry unchanged 401 or 422 responses. Keep retries bounded with backoff, preserve a neutral fallback for optional enrichment, and redact Authorization and X-API-Key from every diagnostic path.
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.