canonical: https://jentic.com/apis/bigdatacloud.net/bigdatacloud

# Bigdatacloud IP Geolocation API

Jentic publishes the only available OpenAPI specification for IP Geolocation API, keeping it validated and agent-ready. BigDataCloud's IP Geolocation API resolves IPv4 addresses to detailed geographic, network, and confidence metadata using the vendor's next-generation lookup engine, with sub-millisecond response times. The service exposes a full lookup endpoint and a confidence-scored variant, both authenticated by an API key passed as a query parameter. BigDataCloud refreshes geolocation data every two hours and offers 10,000 free queries per month before paid tiers kick in.

## For AI agents

Resolve an IPv4 address to country, city, network, and connectivity metadata with a confidence score, using BigDataCloud's two geolocation endpoints.

## Scope

Does not handle IPv6 lookup, reverse DNS, or street-level address geocoding - use for IPv4 geolocation and network ownership only.

## Capabilities

- Resolve an IPv4 address to country, region, and city via `/data/ip-geolocation-full`
- Retrieve ISP, ASN, and BGP network ownership for any IP
- Receive a confidence score on each geolocation result through `/data/ip-geolocation-with-confidence`
- Access BGP routing data refreshed every two hours
- Look up registry-level ownership records updated daily
- Authenticate with a BigDataCloud API key passed as the `key` query parameter

## Use cases

### Visitor Geolocation for Personalisation

Web and SaaS products tailor pricing pages, language defaults, and compliance prompts based on the visitor's country and region. The `/data/ip-geolocation-full` endpoint resolves an IPv4 to country code, city, time zone, and connectivity metadata in a single sub-millisecond call, suitable for inline rendering during page load. The 10,000-query free tier lets a small product run lookups before upgrading at $2 per additional 10K queries.

Example prompt: Call `/data/ip-geolocation-full` with ip=203.0.113.45 and key={BDC_KEY} and return country.isoAlpha2 and location.city

### Fraud Signal Enrichment

Anti-fraud and risk teams enrich each transaction with the ASN, ISP, and confidence-scored location for the originating IP, then feed those signals into a rules engine or ML model. The confidence-scored endpoint `/data/ip-geolocation-with-confidence` flags results where the underlying data conflicts so the system can downweight uncertain matches. BGP refresh every two hours keeps detections current with hijack and re-routing events.

Example prompt: Call `/data/ip-geolocation-with-confidence` with ip from a suspect transaction and forward network.organisation, country.isoAlpha2, and confidence to the rules engine

### Compliance and Geofencing

Streaming platforms, gambling operators, and SaaS vendors enforce geographic licensing by checking each request's IP against a country and region allowlist. BigDataCloud's geolocation is updated every two hours and includes registry-level ownership, helping reduce false positives for travelers on cellular networks. The 1.0.0 spec supports both IPv4 endpoints over HTTPS at api.bigdatacloud.net.

Example prompt: Call `/data/ip-geolocation-full` with the request IP and reject if country.isoAlpha2 is not in {US, CA, GB, IE}

### Agent-Driven IP Enrichment via Jentic

An AI agent investigating a security alert searches Jentic for 'geolocate an IP address', loads the BigDataCloud full lookup operation, and returns the country, ISP, and confidence in one call. Because the API key is held in Jentic's vault, the agent never sees the secret and the same workflow can be reused across alerts. This makes BigDataCloud usable as a tool inside SOC and triage agents without per-agent key plumbing.

Example prompt: Search Jentic for 'geolocate an IP address', load BigDataCloud `/data/ip-geolocation-full`, execute with the alert IP, return country and ISP

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/data/ip-geolocation-full` | Full IPv4 geolocation with country, city, ISP, ASN |
| GET | `/data/ip-geolocation-with-confidence` | Geolocation with a confidence score on the result |

## Key resources

- **IP Geolocation Full** — Full lookup returning country, city, network, registry, and connectivity data
- **IP Geolocation With Confidence** — Confidence-scored geolocation result for risk and uncertainty handling

## Why Jentic

- **Setup:** Wiring the IP Geolocation API by hand means attaching your BigDataCloud API key to every query and picking between the full and confidence-scored geolocation endpoints yourself. Through Jentic you install once, import the IP Geolocation API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** This API takes the IP address as a query parameter rather than pinning a resource in the path, so limit the agent to the operations it needs, such as the full IPv4 geolocation lookup or the confidence-scored variant. You choose that set, so only the endpoints you allow are reachable.
- **Credential handling:** Your BigDataCloud API 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 'get network ownership for an IP', and Jentic returns the matching BigDataCloud operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ipstack API** — Real-time IP-to-location lookup with bulk endpoint support and IPv6
- **ipgeolocation.io API** — Geolocation plus time zone, astronomy, and currency conversion endpoints
- **ipapi API** — JSON IP location lookup with security and connection-type fields

## FAQ

### Why is there no official OpenAPI spec for IP Geolocation API?

BigDataCloud does not publish an OpenAPI specification - the IP Geolocation API is documented in narrative form on bigdatacloud.com. Jentic generates and maintains this spec so that AI agents and developers can call IP 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 Geolocation API use?

The API uses an API key passed as the `key` query parameter on each request. Through Jentic, the BigDataCloud key is stored encrypted in the vault and attached to outbound calls automatically, so the raw key never enters the agent's context.

### What does the confidence score on `/data/ip-geolocation-with-confidence` mean?

The confidence value reflects how well multiple signals (registry, BGP, latency, and historical observations) agree on the returned location. Low scores typically indicate a cellular IP, recently re-allocated address, or a proxy/VPN range - fraud and compliance flows should treat low-confidence matches as soft signals rather than hard ground truth.

### What are the rate limits and pricing for the IP Geolocation API?

BigDataCloud provides 10,000 free queries per month, with additional capacity at $2 per extra 10K queries. There is no hard per-second limit published in the spec - for sustained throughput above the free tier you should batch lookups and use the upgraded plan.

### How do I geolocate an IP through Jentic?

Run `pip install jentic`, then `await client.search('geolocate an IP address')`, `await client.load(...)` for the BigDataCloud `/data/ip-geolocation-full` operation, and `await client.execute(...)` with the IP. Jentic injects the API key from the vault and returns the parsed country, city, and network data.

### Does the API work for IPv6 addresses?

The 1.0.0 spec exposes only IPv4 lookup endpoints. IPv6 addresses are not supported by `/data/ip-geolocation-full` or `/data/ip-geolocation-with-confidence` - for dual-stack workloads, resolve IPv6 traffic to IPv4 upstream or use a complementary provider for v6 ranges.

### Can I limit what my agent is allowed to do with the IP Geolocation API?

Yes. Because your Jentic One instance is self-hosted and governed by your own rules, you decide which BigDataCloud operations the agent may call and which credentials it may use. This API passes the IP as a query parameter rather than pinning a resource in the path, so you scope by operation: allow only the full IPv4 lookup at `/data/ip-geolocation-full`, only the confidence-scored variant at `/data/ip-geolocation-with-confidence`, or both. Only the endpoints you grant are reachable, and your stored API key is attached at execution time without ever entering the agent's context.