canonical: https://jentic.com/apis/ip-api/ip-api # ip-api Geolocation API Jentic publishes the only available OpenAPI specification for ip-api Geolocation API, keeping it validated and agent-ready. ip-api is a free IP geolocation service that returns country, region, city, latitude and longitude, ISP, organisation, AS number, and timezone for any IPv4 or IPv6 address or hostname. The free tier is HTTP-only and limited to non-commercial use; the pro tier at https://pro.ip-api.com adds HTTPS and higher rate limits. The 3-endpoint surface covers single-IP lookups, requester-IP lookups, and a batch endpoint that resolves up to 100 IPs in one call. ## For AI agents Resolve any IP address or hostname to country, city, ISP, ASN, and timezone so an agent can enrich logs, route users, or apply geo-based rules. ## Scope Does not handle proxy or VPN detection, threat intelligence, or domain WHOIS - use for IP and hostname geolocation only. ## Capabilities - Resolve any IPv4 or IPv6 address to country, region, city, latitude, and longitude - Look up the ISP, organisation, and AS number behind an IP address - Geolocate the IP that issued the current request without supplying it explicitly - Batch up to 100 IP addresses into a single POST for log-enrichment workloads - Resolve a hostname through the same endpoint as an IP for hybrid lookups - Return the local timezone for an IP for time-of-day routing decisions ## Use cases ### Web Log Enrichment Operations and security teams can enrich raw web access logs with country, city, and ISP data by feeding IPs through the batch endpoint, which accepts up to 100 IPs per POST. The output adds geographic context to dashboards and lets analysts spot unusual traffic patterns without standing up a local MaxMind database. Example prompt: Send a batch of 50 IP addresses to /batch and return the country and ISP for each one as a CSV. ### Geo-Aware Routing Web applications can call /json/ on a request to obtain the visitor's country and city without supplying the IP explicitly, then route to the closest CDN region or apply locale-specific content rules. The lookup is cheap enough to do on the request path during cold starts. Example prompt: Call /json/ with no IP from the server-side handler and route the response to the EU bucket if country is in the EU country list. ### Fraud and Abuse Triage Trust and safety teams can geolocate IPs surfaced in abuse reports to spot mismatches with the account country, then escalate or block. ip-api returns ISP, ASN, and country in a single call, which is the minimum needed to triage a low-effort fraud signal. Example prompt: Geolocate the IP from a flagged login event and report whether the country differs from the account billing country. ### Agent-Driven Log Triage An AI agent connected via Jentic can enrich a list of suspect IPs with country, ISP, and ASN, summarise the result, and decide whether to escalate or close. The agent searches Jentic by intent rather than wiring the three ip-api endpoints by hand, and Jentic injects the right base URL when an account upgrades to pro.ip-api.com. Example prompt: Take a list of 25 IPs from a security alert, batch-resolve them via /batch, and return a summary grouped by country and ASN. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /json/{query} | Geolocate an IP address or hostname | | GET | /json/ | Geolocate the requesting IP | | POST | /batch | Batch geolocate up to 100 IPs | ## Key resources - **Single Lookup** — Resolve one IP or hostname via /json/{query}. - **Requester Lookup** — Resolve the calling client's IP via /json/. - **Batch Lookup** — Resolve up to 100 IPs in a single POST to /batch. ## Why Jentic - **Setup:** Wiring the ip-api Geolocation API by hand means choosing between the free HTTP origin and the pro HTTPS host, attaching the key query parameter only on the pro tier, and hand-batching lookups yourself. Through Jentic you install once, import ip-api from the API Directory, store the key once for pro use, and your agent calls it. - **Permission scoping:** ip-api is a read-only lookup service where the address travels in the /json/{query} path or the /batch request body, so scoping is by operation: limit the agent to the operations it needs, such as single-IP geolocation or batch lookup. All operations only read location data and write nothing, so there is no destructive operation to include. - **Credential handling:** The free ip-api endpoint is unauthenticated, so Jentic just routes the call, and for pro accounts your key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'geolocate an IP address' or 'batch geolocate many IPs', and Jentic returns the matching ip-api operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **ipapi** — ipapi offers a similar IP geolocation service with HTTPS by default and a key-gated free tier. - **IP2Location.io** — IP2Location.io returns geolocation, ISP, ASN, and proxy detection from one endpoint. - **IP2Proxy** — IP2Proxy adds anonymous proxy, VPN, and TOR exit-node detection that ip-api does not provide. ## FAQ ### Why is there no official OpenAPI spec for ip-api Geolocation API? ip-api does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call ip-api Geolocation API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the ip-api Geolocation API use? The free tier at http://ip-api.com requires no authentication. The pro tier at https://pro.ip-api.com requires an API key passed as the 'key' query parameter; through Jentic that key is held in the encrypted vault and appended at execution time. ### Can I batch lookups instead of calling once per IP? Yes. POST a JSON array of up to 100 IP addresses or hostnames to /batch and the response returns one entry per query in the same order. This is the recommended pattern for log enrichment workloads. ### What are the rate limits for the ip-api Geolocation API? The free endpoint allows 45 requests per minute per source IP and the response includes X-Rl and X-Ttl headers showing remaining quota and reset time. The pro tier removes that limit and the documentation lists the per-plan throughput. ### How do I geolocate an IP through Jentic? Search Jentic for 'geolocate an IP address', load the schema for GET /json/{query}, and execute with the IP. Run pip install jentic, then await client.search, await client.load, await client.execute. ### Does ip-api support IPv6 and hostnames? Yes. The /json/{query} endpoint accepts IPv4 addresses, IPv6 addresses, and hostnames; the response shape is the same for all three so an agent does not need to branch on input type.