BigDataCloud Go SDK

Official Go SDK for BigDataCloud APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, and Network Engineering — plus a GraphQL interface for all packages.

Zero external dependencies — stdlib net/http only.

Installation

go get github.com/bigdatacloudapi/bigdatacloud-go

API Key

Get a free API key at bigdatacloud.com/login. No credit card required.

export BIGDATACLOUD_API_KEY=your-key-here

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    bdc "github.com/bigdatacloudapi/bigdatacloud-go/bigdatacloud"
)

func main() {
    // Reads BIGDATACLOUD_API_KEY from environment
    client, err := bdc.NewClientFromEnvironment()
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    ctx := context.Background()

    // IP Geolocation
    geo, err := client.IPGeolocation.Get(ctx, "1.1.1.1", "en")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s, %s\n", geo.Location.City, geo.Country.Name)

    // Reverse Geocoding
    place, err := client.ReverseGeocoding.ReverseGeocode(ctx, -33.87, 151.21, "en")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s, %s\n", place.City, place.CountryName)

    // Phone Validation — countryCode required
    phone, err := client.Verification.ValidatePhone(ctx, "+61412345678", "AU")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Valid: %v, Type: %s\n", phone.IsValid, phone.LineType)

    // Email Verification
    email, err := client.Verification.VerifyEmail(ctx, "user@example.com")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Valid: %v, Disposable: %v\n", email.IsValid, email.IsDisposable)
}

Confidence Area

The ConfidenceArea field may encode multiple polygons in a flat slice. Use the helper:

geo, _ := client.IPGeolocation.GetWithConfidenceArea(ctx, "1.1.1.1", "en")
polygons := bdc.SplitIntoPolygons(geo.ConfidenceArea)
for i, ring := range polygons {
    fmt.Printf("Ring %d: %d points\n", i+1, len(ring))
}

Available APIs

Client	Methods
client.IPGeolocation	Get, GetWithConfidenceArea, GetFull, GetCountryByIP, GetCountryInfo, GetAllCountries, GetHazardReport, GetUserRisk, GetASNInfo, GetNetworkByIP, GetTimezoneByIANAID, GetTimezoneByIP, ParseUserAgent
client.ReverseGeocoding	ReverseGeocode, ReverseGeocodeWithTimezone, GetTimezoneByLocation
client.Verification	ValidatePhone, ValidatePhoneByIP, VerifyEmail
client.NetworkEngineering	GetASNInfoFull, GetReceivingFrom, GetTransitTo, GetBGPPrefixes, GetNetworksByCIDR, GetASNRankList, GetTorExitNodes

Phone Validation

Both methods require explicit country context — never uses server IP silently:

// You know the country
phone, err := client.Verification.ValidatePhone(ctx, "+61412345678", "AU")

// You know the end user's IP (pass their IP, not your server's)
phone, err := client.Verification.ValidatePhoneByIP(ctx, "0412345678", userIP)

Samples

export BIGDATACLOUD_API_KEY=your-key-here
go run samples/ip_geolocation/main.go
go run samples/reverse_geocoding/main.go
go run samples/verification/main.go
go run samples/network_engineering/main.go

Error Handling

geo, err := client.IPGeolocation.Get(ctx, "1.1.1.1", "en")
if err != nil {
    if apiErr, ok := err.(*bdc.APIError); ok {
        fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Body)
    }
    log.Fatal(err)
}

License

MIT — see LICENSE.