GraphQL

BigDataCloud is the only IP geolocation provider offering a full GraphQL API. Unlike REST endpoints that return fixed response shapes, GraphQL lets you request exactly the fields you need — nothing more. This means smaller payloads, faster responses, and less wasted data.

Every package on BigDataCloud has a corresponding GraphQL endpoint. Use the same API key for authentication.

Endpoint Format

All GraphQL requests use POST to the following URL pattern:

POST https://api-bdc.net/graphql/{package-name}

Available Endpoints

Example Query

Request only the fields you need — GraphQL returns exactly what you ask for:

# Request only the fields you need
{
  ipGeolocation(ip: "1.1.1.1") {
    location { city country }
    confidence
    network { organisation }
  }
}

Example Request

Send the query as JSON using the x-bdc-key header for authentication:

curl -X POST https://api-bdc.net/graphql/ip-geolocation \
  -H "Content-Type: application/json" \
  -H "x-bdc-key: YOUR_API_KEY" \
  -d '{"query": "{ ipGeolocation(ip: \"1.1.1.1\") { location { city } confidence } }"}'

Interactive Playgrounds

Each API package has a live GraphQL playground. Sign in to authenticate automatically with your API key.