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

Pol Nisenblat — Mon, 13 Apr 2026 05:15:01 +0000

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

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

Free Location Detection in React — One Hook, Zero Configuration

Pol Nisenblat — Wed, 18 Mar 2026 23:06:43 +0000

Adding location awareness to a React app usually means signing up for a geocoding service, managing API keys, and writing fallback logic. What if you could skip all of that?

30-Second Setup

npm install @bigdatacloudapi/react-reverse-geocode-client
import { useGeoLocation } from '@bigdatacloudapi/react-reverse-geocode-client';

function App() {
  const { data, loading, error, source } = useGeoLocation();

  if (loading) return <p>Detecting location...</p>;
  if (error) return <p>Error: {error}</p>;

  return (
    <div>
      <h1>📍 {data?.city}, {data?.countryName}</h1>
      <p>Region: {data?.principalSubdivision}</p>
      <p>Detected via: {source}</p>
    </div>
  );
}

That's the entire integration. No API key, no account, no configuration.

How It Works

The useGeoLocation() hook implements a two-tier detection strategy:

GPS first — requests the browser's geolocation (user sees a permission prompt)
Automatic IP fallback — if GPS is denied or unavailable, resolves location from the user's IP address

Both paths return the identical JSON structure. Your UI code doesn't need to handle two different response formats.

Why It's Free

There's no catch. When the hook sends GPS coordinates, the browser also reveals its IP address. This anonymous pairing helps BigDataCloud continuously validate their IP geolocation accuracy — which they benchmark daily in a public accuracy report. You provide location context, they provide the geocoding. Fair exchange.

Features

• ✅ No API key — works out of the box
• ✅ GPS with automatic IP fallback
• ✅ 100+ languages ({ language: 'ja' } for Japanese)
• ✅ Full TypeScript types
• ✅ SSR/Next.js compatible
• ✅ Manual trigger mode for "Detect My Location" buttons

Multi-language Example

const { data } = useGeoLocation({ language: 'ja' });
// data.countryName → "日本"
// data.city → "東京"

Manual Trigger

function SearchButton() {
  const { data, loading, refresh } = useGeoLocation({ manual: true });

  return (
    <button onClick={refresh} disabled={loading}>
      {loading ? 'Detecting...' : 'Detect My Location'}
    </button>
  );
}

Next.js / SSR

Works in client components:

'use client';
import { useGeoLocation } from '@bigdatacloudapi/react-reverse-geocode-client';

Fair Use

The free client-side API is for production client-side use only. For development and testing, use the server-side API with a free API key. See the fair use policy.

Links

• 📦 npm
• 💻 GitHub
• 🌐 BigDataCloud

Also available for Vue/Nuxt: @bigdatacloudapi/vue-reverse-geocode-client

Canonical URL: https://www.bigdatacloud.com/blog/free-location-detection-in-react

DEV Community: Pol Nisenblat

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

Free Location Detection in React — One Hook, Zero Configuration