How to Use BigDataCloud: APIs, Keys & First Requests
How to Use BigDataCloud: APIs, Keys & First Requests
BigDataCloud is a location intelligence platform that provides IP geolocation, reverse geocoding, phone and email verification, and network intelligence APIs. The platform is built around a simple idea: you should be able to start with accurate location data in minutes without a credit card. This guide walks through the practical steps of using BigDataCloud, from understanding the API packages to making your first request and avoiding common fair use mistakes.
What BigDataCloud Offers
How to Use BigDataCloud: APIs, Keys & First Requests - What BigDataCloud Offers.
BigDataCloud organizes its services into four focused API packages:
- IP Geolocation — maps an IP address to city, country, coordinates, confidence area, ISP, ASN, and hazard flags such as VPN, proxy, or Tor detection.
- Reverse Geocoding — converts latitude and longitude coordinates into a human-readable address or location description.
- Verification — validates phone numbers and email addresses.
- Network Intelligence — explores network data such as prefixes, ASNs, and related infrastructure.
Every package includes a free tier, and every plan includes all endpoints and all response fields. You pay only for volume, not for feature unlocks. The platform also offers both REST and GraphQL access, which is unusual among IP geolocation providers.
Step 1: Explore the Free Client-Side APIs Without an Account
How to Use BigDataCloud: APIs, Keys & First Requests - Step 1: Explore the Free Client-Side APIs Without an Account.
BigDataCloud provides a set of free client-side APIs that require no account and no API key. These are designed to run directly in a browser or mobile app. The main free client-side endpoints include:
- Client-side reverse geocoding
- Client-side IP detection
- Roaming detection
To try these, visit the API package pages on the BigDataCloud site, open the API Endpoints section, and click View Documentation on the endpoint you want. The documentation includes sample requests and response formats you can test immediately.
The free client-side reverse geocoding API is particularly useful for web projects that already use the HTML5 Geolocation API. You can retrieve the user's current coordinates on the client and convert them to a location description without any server-side infrastructure.
Fair Use Rules for the Free Client-Side Reverse Geocoding API
The free client-side reverse geocoding endpoint has strict usage rules that are easy to violate accidentally:
- The API must only convert current geo-coordinates obtained with permission from the calling client device.
- You must not pass pre-stored coordinates or coordinates belonging to another user.
- Coordinates must reflect the calling device's best-known location, retrieved via client-side geolocation services such as GPS or Wi-Fi positioning.
- The API call must originate from the same client where the coordinates were retrieved. You may not retrieve coordinates on the client, send them to a server, and then call the API from that server.
Violating these rules can result in your IP address being banned from all of BigDataCloud's free APIs, with requests returning a 402 error. If you need server-side reverse geocoding, use the dedicated server-side endpoint instead. It returns the same data, includes 50,000 free queries per month, and requires an API key.
Step 2: Register for a Free API Key
How to Use BigDataCloud: APIs, Keys & First Requests - Step 2: Register for a Free API Key.
For access to the full suite of endpoints, create a free account using the registration button in the top-right corner of the BigDataCloud website. The signup process takes about 30 seconds and does not require a credit card.
After registration, you receive a unique API key. BigDataCloud notes that it can take up to 10 minutes for the key to propagate across its API server network. You will receive an email notification when the key is activated. If you try to make requests before propagation completes, you may see authentication errors, so it is worth waiting for the confirmation email.
The free tier is generous enough for development and moderate production use. Depending on the API package, free quotas range from 10,000 to 50,000 calls per month.
Step 3: Make Your First IP Geolocation Request
Once your key is active, you can make a REST request to the IP geolocation endpoint. A basic request looks like this:
GET /data/ip-geolocation?ip=1.1.1.1&key=YOUR_KEY
The full REST response returns approximately 2 KB of data with 50+ fields, including:
- The IP address
- Location details such as city, country code, latitude, and longitude
- A confidence score
- Network information including ISP, ASN, and prefixes
- A hazard report flagging VPN, proxy, or Tor usage
If you only need a few fields, the GraphQL endpoint can reduce the response size dramatically. For example, requesting only city, country code, and confidence returns roughly 200 bytes instead of 2 KB:
query {
ipGeolocation(ip: "1.1.1.1") {
location { city countryCode }
confidence
}
}
Both REST and GraphQL return the same underlying data at the same price. GraphQL is simply a way to request exactly the fields you need, which is valuable for mobile applications or high-volume integrations where response size matters.
Step 4: Use Official SDKs and AI Integration
BigDataCloud provides official SDKs for major programming languages with typed models and working samples. This reduces the boilerplate code required to integrate the APIs into production applications.
The platform also supports MCP (Model Context Protocol) integration, which allows AI assistants such as Claude, Cursor, and VS Code to geolocate IPs, reverse geocode coordinates, and validate data directly. A basic MCP configuration looks like this:
{
"bigdatacloud": {
"command": "npx",
"args": ["-y", "@bigdatacloudapi/mcp-server"]
}
}
This is useful for developers building AI-powered applications that need location context without writing custom API glue code.
Practical Use Cases
BigDataCloud's APIs fit into several common workflows:
- Fraud prevention — use the hazard report to flag IPs associated with VPNs, proxies, or Tor exit nodes before processing transactions.
- Localization — geolocate a visitor's IP to serve region-specific content, currency, or language.
- Log analysis — enrich server logs with location and network intelligence to understand where traffic originates.
- Mobile apps — use client-side reverse geocoding to convert GPS coordinates into readable locations without server round trips.
- AI assistants — connect the MCP server to give AI tools real-time location intelligence capabilities.
Verifying Your Own IP and Network Data
When you work with IP geolocation APIs, it is worth checking what your own browser and network reveal. A tool like BrowserScan lets you run a browser fingerprint analysis, DNS and WebRTC leak tests, and an IP address lookup with geolocation, ISP, and proxy detection. This is useful for confirming that a VPN is not leaking your real IP or that your browser fingerprint looks authentic before you rely on geolocation data in production. For a deeper understanding of how location data is used in analytics and decision-making, see this guide on location intelligence.
Choosing Between Free Client-Side and Server-Side APIs
| Scenario | Recommended API |
|---|---|
| Web app using HTML5 Geolocation, no backend | Free client-side reverse geocoding |
| Mobile app with native location SDK, no backend call | Free client-side reverse geocoding |
| Server needs to reverse geocode stored or third-party coordinates | Server-side reverse geocoding with API key |
| High-volume production IP geolocation | Server-side IP geolocation with API key |
| Minimal response size for mobile or embedded systems | GraphQL endpoint |
The key distinction is where the coordinates come from and where the API call happens. If both happen on the same client device with the user's current location, the free client-side endpoint is appropriate. Any other pattern requires the server-side API.
Related reading
- What Is a Personal VPN? How to Choose and Test One - Learn what a personal VPN does, how it protects your IP and traffic, how to choose the right service, and how to verify your connection for leaks.
Sources and further reading
- Getting started with BigDataCloud API - Patented IP geolocation with daily public accuracy benchmarks. Free to start, scales to billions.
- Free Client-side Reverse Geocoding API: Usage Guidelines and Fair Use Policy - Learn how to use BigDataCloud's Free Client-side Reverse Geocoding API responsibly. Follow our fair use policy for reliable access or explore server-side alternatives
- BigDataCloud - Precise IP Geolocation & Reverse Geocoding APIs - Patented IP geolocation with daily public accuracy benchmarks. Confidence areas, hazard detection, ASN intelligence. Free to start.
Frequently Asked Questions
Do I need a credit card to start using BigDataCloud?
No. The free tier requires no credit card and no commitment. You can sign up, receive an API key, and make your first request within minutes.
How long does API key activation take?
BigDataCloud states that key propagation can take up to 10 minutes across its server network. You will receive an email when your key is active.
What happens if I violate the fair use policy for the free client-side reverse geocoding API?
Your IP address may be banned from all of BigDataCloud's free APIs, and requests will return a 402 error. You can contact BigDataCloud to request a review.
Can I use the free client-side reverse geocoding API from a server?
No. The call must originate from the same client device where the coordinates were retrieved. For server-side use, switch to the server-side reverse geocoding API, which includes 50,000 free queries per month.
What is the difference between REST and GraphQL on BigDataCloud?
Both return the same data at the same price. REST returns a full response object with 50+ fields, while GraphQL lets you request only the fields you need, reducing response size from around 2 KB to as little as 200 bytes.
What free quota does BigDataCloud provide?
Free quotas range from 10,000 to 50,000 calls per month depending on the API package. Paid plans start at $19.95 per month for the Bronze tier.
Conclusion
BigDataCloud is designed to get you from signup to working API calls in minutes. Start with the free client-side endpoints to explore the data without an account, then register for a key when you need server-side access or higher volume. Pay attention to the fair use policy for the free client-side reverse geocoding API, since violations can result in IP bans. Once you are set up, choose REST for full responses or GraphQL for minimal payloads, and consider the official SDKs or MCP integration if you are building a larger application.
For more on the broader ecosystem of IP and network tools, see this comparison of BrowserLeaks pricing and free tools or learn how to run your own Nmap port scans.