canonical: https://jentic.com/apis/ipgeolocation.io/ipgeolocation

# ipgeolocation.io API

Look up geolocation, security threat data, ASN details, timezone information, astronomy data, and user-agent metadata for any IPv4 or IPv6 address. The API supports single and bulk lookups (up to 50,000 IPs per request), timezone conversion between locations, astronomical event calculations for any date and coordinates, and browser/device detection from user-agent strings across 13 endpoints with multi-language responses.

## For AI agents

Geolocate IP addresses, detect security threats (VPN, proxy, Tor), look up ASN and timezone data, and parse user-agent strings. Supports bulk lookups of up to 50,000 IPs per request.

## Scope

Does not handle address-to-coordinate geocoding, route planning, or map rendering - use for IP-based geolocation, security detection, and astronomical data only.

## Capabilities

- Geolocate IPv4 and IPv6 addresses to country, city, coordinates, ISP, and currency in 12 languages
- Detect VPNs, proxies, Tor exit nodes, and known attackers with threat confidence scores
- Look up Autonomous System Number details including peers, routes, and upstream/downstream providers
- Retrieve timezone and local time for any IP, coordinates, address, or IATA/ICAO airport code
- Convert timestamps between timezones using location names, coordinates, or timezone identifiers
- Calculate sunrise, sunset, moonrise, golden hour, and twilight phases for any location and date range
- Parse user-agent strings into structured browser, device, and OS metadata

## Use cases

### AI Agent IP Geolocation via Jentic

AI agents handling geo-targeted content delivery or access control can geolocate visitor IPs through Jentic. The agent passes an IP address and receives structured location data including country, city, coordinates, ISP, and local currency - enabling automated content localisation, pricing, and compliance checks.

Example prompt: Search Jentic for 'geolocate IP address', load the ipgeolocation.io /v3/ipgeo schema, and query with ip='8.8.8.8' to retrieve country, city, coordinates, and timezone

### Fraud Detection and IP Security Screening

Payment processors, login systems, and anti-fraud platforms screen IP addresses for security threats before allowing transactions. The security endpoint returns VPN/proxy/Tor detection, threat scores, and known attacker flags - each lookup costs 2 credits and supports bulk analysis of up to 50,000 IPs for batch fraud reviews.

Example prompt: GET /v3/security with ip='198.51.100.23' to retrieve the threat_score, is_vpn, is_proxy, is_tor, and is_known_attacker flags

### Timezone-Aware Scheduling and Communication

Scheduling applications and communication platforms determine the recipient's local time before sending notifications or booking meetings. The timezone endpoint accepts IPs, coordinates, addresses, or IATA codes and returns current local time, UTC offset, and DST status, while the conversion endpoint translates timestamps between any two timezones.

Example prompt: GET /v3/timezone with ip='203.0.113.50' to retrieve the timezone name, current local time, UTC offset, and DST status for scheduling

### Astronomy and Solar Event Calculations

Weather apps, photography planning tools, and outdoor activity platforms calculate solar and lunar events for specific dates and locations. The astronomy endpoint returns sunrise, sunset, golden hour, twilight phases, moonrise, moonset, and moon illumination percentage, with time series support for date ranges up to 90 days.

Example prompt: GET /v3/astronomy with lat=40.7128, long=-74.0060, date='2026-06-21' to retrieve sunrise, sunset, golden hour, and moon phase for New York on the summer solstice

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v3/ipgeo | Geolocate a single IP address or domain |
| POST | /v3/ipgeo-bulk | Bulk geolocate up to 50,000 IPs |
| GET | /v3/security | Detect security threats for an IP |
| GET | /v3/asn | Look up ASN details by AS number or IP |
| GET | /v3/timezone | Get timezone and local time for a location |
| GET | /v3/timezone/convert | Convert time between two timezones |
| GET | /v3/astronomy | Get sun/moon rise/set and astronomical data |
| GET | /v3/getip | Get the caller's IP address |

## Key resources

- **IP Geolocation** — Single and bulk IP-to-location lookups with country, city, coordinates, ISP, and currency data
- **IP Security** — Threat detection for VPNs, proxies, Tor nodes, bots, and known attackers with confidence scores
- **ASN** — Autonomous System Number lookups with peers, routes, upstreams, and downstreams
- **Timezone** — Timezone lookup by IP, coordinates, or address with time conversion between zones
- **Astronomy** — Solar and lunar event calculations including sunrise, sunset, golden hour, and moon phases
- **User Agent** — Parse user-agent strings into browser, device, engine, and OS metadata

## Why Jentic

- **Setup:** Wiring ipgeolocation.io by hand means registering for a key, appending it as the apiKey query parameter to api.ipgeolocation.io, and choosing among the v3 geolocation, security, ASN, timezone, and astronomy endpoints yourself. Through Jentic you install once, import ipgeolocation.io from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** ipgeolocation.io is a set of read-only lookups where the IP or coordinate travels as a query parameter, so scope the agent to the operations it needs, such as geolocating an IP or detecting a VPN. It stays a lookup client and cannot reach anything beyond the operations you allow.
- **Credential handling:** Your ipgeolocation.io API key is stored once, encrypted, by your own Jentic One instance and injected as the apiKey query parameter 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 'detect a VPN proxy', and Jentic returns the matching ipgeolocation.io operation with its input schema, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ipstack API** — IP geolocation with currency, timezone, and security modules - fewer endpoints but similar core functionality
- **Abstract IP Geolocation API** — Simple IP geolocation focused on location data with a clean REST interface
- **LocationIQ API** — Forward and reverse geocoding for addresses and coordinates, complementing IP-based location data

## FAQ

### What authentication does the ipgeolocation.io API use?

The API uses an API key passed as a query parameter named 'apiKey' on every request. The free plan allows 1,000 requests per day. Through Jentic, this key is stored encrypted in the credential vault and appended automatically - agents never handle the raw key.

### Can I geolocate multiple IP addresses in one request?

Yes. The /v3/ipgeo-bulk endpoint accepts a POST request with an array of up to 50,000 IP addresses or domain names. Each IP in the array returns the same geolocation fields as the single-IP endpoint, making batch processing efficient.

### What are the rate limits for the ipgeolocation.io API?

The free plan allows 1,000 requests per day with a 429 status returned when exceeded. Paid plans offer higher daily and per-second limits. Security lookups cost 2 credits per IP. Bulk endpoints count each IP in the array as a separate credit.

### How do I detect whether an IP is a VPN or proxy through Jentic?

Install the SDK with pip install jentic and search for 'detect VPN proxy IP'. Jentic returns the ipgeolocation.io /v3/security operation schema. Pass the target IP and receive is_vpn, is_proxy, is_tor, threat_score, and confidence scores.

### Can I get astronomy data for a range of dates?

Yes. The /v3/astronomy/timeSeries endpoint accepts dateStart and dateEnd parameters (maximum 90-day span) along with coordinates. It returns an array of astronomy objects - one per day - with sunrise, sunset, moonrise, moon phase, golden hour, and twilight data.

### Does the timezone endpoint support conversion between two zones?

Yes. The /v3/timezone/convert endpoint accepts source and target locations (by timezone name, coordinates, or address) plus a timestamp. It returns the converted time, hour difference, and minute difference between the two zones.

### Can I limit what my agent is allowed to do with the ipgeolocation.io API?

Yes. Because you run Jentic One yourself, your own rules decide which ipgeolocation.io operations the agent may call and which credentials it may use. Since these are all read-only lookups where the IP or coordinate travels as a query parameter, you can scope the agent to just the operations it needs, such as geolocating an IP with /v3/ipgeo while denying VPN and threat detection on /v3/security or timezone conversion on /v3/timezone/convert. It stays a lookup client and cannot reach anything beyond the operations you allow.