DEV Community

Pol Nisenblat
Pol Nisenblat

Posted on

We built official SDKs for 8 languages for our IP geolocation API — here's what we learned

After years of maintaining a single basic JavaScript client, we spent the first part of 2026 building proper SDKs for BigDataCloud across every major language. Here's what shipped and a few things we learned along the way.

What we built

Official SDKs for Node.js/TypeScript, Python, PHP, .NET/C#, Java, Go, Ruby and Rust — each covering all four of our API packages:

  • IP Geolocation — city, country, ASN, hazard report, confidence area, timezone, user agent parsing
  • Reverse Geocoding — GPS coordinates to locality, city, subdivision, country
  • Phone & Email Verification — E.164 formatting, line type detection, MX validation, disposable detection
  • Network Engineering — BGP prefixes, ASN peers, Tor exit nodes, CIDR lookups

We also built free client-side libraries for React, Vue, React Native, Swift (iOS/macOS/watchOS), Kotlin (Android) and Flutter — GPS-first with automatic IP fallback, no API key needed.

The design decisions that mattered

One consistent pattern across all languages

Every SDK follows the same structure: four API group objects on a single client, a fromEnvironment() factory reading BIGDATACLOUD_API_KEY, and a splitIntoPolygons() helper for confidence area handling. A Python developer and a Go developer should look at the code and immediately understand what the other one is doing.

Confidence area polygons are tricky

Our IP geolocation API returns a confidenceArea field — a flat array of coordinates that encodes multiple polygon rings. The closing coordinate of each ring matches its opening coordinate. This is simple in theory but breaks in practice when consumers treat the whole array as one polygon. Every SDK ships a SplitIntoPolygons() helper, and we documented the gotcha clearly.

Phone validation needs explicit country context

validatePhone(number) with no country hint silently uses the server's IP for country detection — which on a cloud server returns the wrong country for your users. We made countryCode a required parameter in every SDK. A bit more friction upfront, a lot less confusion later.

asnNumeric needs to be long in Java

Some ASN numbers exceed Integer.MAX_VALUE (2^31). We discovered this only after running the Java SDK against the live API and hitting a deserialization error on a real ASN. Every other language handles this implicitly — Java doesn't.

The client-side fair use challenge

The free client-side libraries use a no-key endpoint (api.bigdatacloud.net) that's governed by a fair use policy: only real-time device GPS coordinates, never pre-stored or server-side coordinates. We removed the reverseGeocode(lat, lng) override from the client libraries entirely — it would have been too easy to misuse the free endpoint by routing server-side batch geocoding through it.

GraphQL

We're one of the few geolocation providers with a GraphQL API. The Python and .NET SDKs include typed query builders — fluent interfaces that generate the GraphQL query string, give you IntelliSense, and make it obvious which fields cost bandwidth.

Try it

# Node.js
npm install bigdatacloud

# Python
pip install bigdatacloud

# Go
go get github.com/bigdatacloudapi/bigdatacloud-go

# Rust
cargo add bigdatacloud
Enter fullscreen mode Exit fullscreen mode

Free tier on all packages, no credit card required. Full SDK list and install instructions at bigdatacloud.com/docs/sdks.

Top comments (0)