Authentication
Authenticate your API requests using an API key — passed as a query parameter or HTTP header.
API Keys
Every BigDataCloud account comes with an API key, generated automatically when you sign up. You can find it in your dashboard under Account → Credentials.
Keep your key secret. Don't commit it to public repositories or expose it in client-side code. Use environment variables or a server-side proxy for production applications.
If your key is compromised, you can regenerate it from the dashboard. The old key will be immediately invalidated.
Authentication Methods
You can authenticate using either a query parameter or an HTTP header. Both methods are equivalent.
Query Parameter
Append key=YOUR_KEY to any API endpoint URL.
curl "https://api-bdc.net/data/ip-geolocation?ip=1.1.1.1&key=YOUR_KEY"HTTP Header
Send your key in the x-bdc-key header. This keeps your key out of URLs and server logs.
curl "https://api-bdc.net/data/ip-geolocation?ip=1.1.1.1" \
-H "x-bdc-key: YOUR_KEY"Free Endpoints (No Key Required)
Some endpoints work without an API key and can be called directly from client-side JavaScript. These are designed for browser-based applications where exposing a key isn't practical.
Client-side Reverse Geocoding
Get address from browser geolocation coordinates — works directly from the browser with no API key.
Am I Roaming
Detect whether the device is roaming outside its home country — useful for mobile apps and personalisation logic.
Free endpoints are for client-side use only — browsers and mobile apps. Do not call them from a server.
Monthly Volume Limits
BigDataCloud uses monthly query volume limits, not per-second or per-minute rate limits. Your API key works at full speed up to your monthly volume.
There are no per-second or per-minute rate limits. Your API key works at full speed up to your monthly volume.
All subscription levels get access to the same endpoints and the same data — you only pay for volume. The free tier includes a generous monthly allowance that varies by package.
When you exceed your monthly limit, the API returns an HTTP 402 response. You can upgrade your plan anytime at /pricing.
Error Responses
Authentication errors return standard HTTP status codes:
| Status | Meaning |
|---|---|
401 | Invalid or missing API key |
403 | Key valid but insufficient permissions for this endpoint |
402 | Monthly volume limit exceeded — upgrade at /pricing |