Authentication
Authenticate your API requests using an API key — passed as a query parameter or HTTP header.
On this page
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-full?ip=54.91.86.70&localityLanguage=en&key=YOUR_KEY"Use country first, then confidenceArea (the service area of the network that delivers the address), then location (the pin); polygon size is not confidence.
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-full?ip=54.91.86.70&localityLanguage=en" \
-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 HTTP 403. The description is the maximum allowed amount of monthly api requests has been reached. please try again after … followed by the UTC time you can try again, in RFC 1123 format. You can upgrade your plan anytime at /pricing.
Error Responses
The API returns these HTTP status codes:
| Status | Meaning |
|---|---|
403 | Missing or invalid API key. The body is {"status":403,"description":"access denied or your quota limit has been exceeded"}. |
403 | Monthly quota exceeded. The description is the maximum allowed amount of monthly api requests has been reached. please try again after … followed by the UTC time you can try again, in RFC 1123 format. |
402 | This endpoint is for client-side use only and was called from a server. Repeated calls can get the caller's IP address banned. |
401 | Invalid coordinates. The description is invalid coordinates. expecting latitude in (+/- 90) and longitude in (+/- 180) range values. |