IP Geolocation API

Get comprehensive location data for any IP address, including timezone, currency, and network information.

Endpoint

GET /v1/geo/lookup

Parameters

Parameter	Type	Required	Description
ip	string	No	IP to look up. Defaults to caller's IP.

Request

cURL

# Look up specific IP
curl -H "X-API-Key: hb_live_xxxxx" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8"

# Look up caller's IP
curl -H "X-API-Key: hb_live_xxxxx" \
  "https://api.hummingbirdapi.com/v1/geo/lookup"

JavaScript

// Look up specific IP
const response = await fetch(
  'https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8',
  { headers: { 'X-API-Key': 'hb_live_xxxxx' } }
);
const { data } = await response.json();
console.log(data.location.city_name); // "Mountain View"
console.log(data.time.zone);          // "America/Los_Angeles"
console.log(data.currency.symbol);    // "$"

Python

import requests

# Look up specific IP
response = requests.get(
    'https://api.hummingbirdapi.com/v1/geo/lookup',
    params={'ip': '8.8.8.8'},
    headers={'X-API-Key': 'hb_live_xxxxx'}
)
data = response.json()['data']
print(data['location']['city_name'])  # Mountain View
print(data['time']['zone'])           # America/Los_Angeles
print(data['currency']['symbol'])     # $

Go

req, _ := http.NewRequest("GET",
    "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8", nil)
req.Header.Set("X-API-Key", "hb_live_xxxxx")

resp, _ := client.Do(req)
defer resp.Body.Close()

var result GeoResponse
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result.Data.Location.CityName)

Ruby

require 'httparty'

response = HTTParty.get(
  'https://api.hummingbirdapi.com/v1/geo/lookup',
  query: { ip: '8.8.8.8' },
  headers: { 'X-API-Key' => 'hb_live_xxxxx' }
)
data = response.parsed_response['data']
puts data['location']['city_name']

PHP

$response = Http::withHeaders([
    'X-API-Key' => 'hb_live_xxxxx'
])->get('https://api.hummingbirdapi.com/v1/geo/lookup', [
    'ip' => '8.8.8.8'
]);

$data = $response->json()['data'];
echo $data['location']['city_name'];

Response

All responses use the unified envelope format with fields in this order: success, data, error, error_code, error_message.

{
  "success": true,
  "data": {
    "ip": "8.8.8.8",
    "ip_type": "ipv4",

    "location": {
      "continent_code": "NA",
      "continent_name": "North America",
      "country_code": "US",
      "country_code_iso3": "USA",
      "country_name": "United States",
      "country_capital": "Washington",
      "country_tld": ".us",
      "country_calling_code": "+1",
      "country_flag_emoji": "🇺🇸",
      "country_languages": ["en", "es"],
      "country_area_km2": 9833520,
      "country_population": 331449281,
      "country_neighbors": ["CA", "MX"],
      "country_is_eu": false,
      "region_code": "CA",
      "region_name": "California",
      "city_name": "Mountain View",
      "postal_code": "94043",
      "latitude": 37.386,
      "longitude": -122.084,
      "weather_code": "USCA0746"
    },

    "time": {
      "zone": "America/Los_Angeles",
      "abbr": "PST",
      "utc_offset": "-08:00",
      "utc_offset_seconds": -28800,
      "current_time": "2026-01-26T10:30:00-08:00",
      "current_timestamp": 1737913800,
      "is_dst": false
    },

    "currency": {
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$"
    },

    "network": {
      "asn": 15169,
      "asn_organization": "Google LLC",
      "isp": "Google LLC",
      "organization": "Google LLC",
      "connection_type": "Corporate",
      "user_type": "hosting"
    }
  },
  "error": false,
  "error_code": null,
  "error_message": null
}

Response Fields

Root Level

Field	Type	Description
ip	string	IP address looked up
ip_type	string	"ipv4" or "ipv6"

location Object

Field	Type	Description
continent_code	string	Two-letter continent code
continent_name	string	Continent name
country_code	string	ISO 3166-1 alpha-2 country code
country_code_iso3	string	ISO 3166-1 alpha-3 country code
country_name	string	Country name
country_capital	string	Capital city
country_tld	string	Top-level domain
country_calling_code	string	International calling code
country_flag_emoji	string	Flag emoji
country_languages	string[]	Primary languages
country_area_km2	number	Area in km²
country_population	number	Population
country_neighbors	string[]	Neighboring countries
country_is_eu	boolean	EU membership
region_code	string	Region/state code
region_name	string	Region/state name
city_name	string	City name
postal_code	string	Postal/ZIP code
latitude	number	Latitude
longitude	number	Longitude
weather_code	string	Weather station code

time Object

Field	Type	Description
zone	string	IANA timezone
abbr	string	Timezone abbreviation
utc_offset	string	UTC offset (±HH:MM)
utc_offset_seconds	number	UTC offset in seconds
current_time	string	Current local time (ISO 8601)
current_timestamp	number	Unix timestamp
is_dst	boolean	Daylight saving active

currency Object

Field	Type	Description
code	string	ISO 4217 currency code
name	string	Currency name
symbol	string	Currency symbol

network Object

Field	Type	Description
asn	number	Autonomous System Number (optional)
asn_organization	string	ASN organization name
isp	string	Internet Service Provider
organization	string	Organization name
connection_type	string	Connection type
user_type	string	User type

Supported Formats

• IPv4: 192.168.1.1
• IPv6: 2001:4860:4860::8888

Errors

Code	Message	Fix
10001	Invalid IP address format	Check IP format
10002	Cannot geolocate private IP	Use public IP
20001	Missing API key	Add header
20002	Invalid API key	Check key
30001	Rate limit exceeded	Wait and retry
30002	Quota exceeded	Upgrade plan

Use Cases

Localization

const { location, currency } = (await lookupIP(userIP)).data;

// Display prices in local currency
if (currency.code === 'EUR') {
  showEuroPricing();
} else if (currency.code === 'GBP') {
  showPoundPricing();
}

// Show country flag
document.getElementById('flag').textContent = location.country_flag_emoji;

GDPR Compliance

const { location } = (await lookupIP(userIP)).data;

if (location.country_is_eu) {
  showCookieConsent();
}

Time-Aware Features

const { time } = (await lookupIP(userIP)).data;

// Schedule messages based on user's local time
const userHour = new Date(time.current_time).getHours();
if (userHour >= 9 && userHour <= 17) {
  showLiveChat();
}

Analytics

const { location, network } = (await lookupIP(userIP)).data;

analytics.track('page_view', {
  country: location.country_code,
  region: location.region_name,
  city: location.city_name,
  isp: network.isp,
  connection_type: network.connection_type
});

Performance

Metric	Value
Median latency	<100ms
Edge locations	300+
Uptime SLA	99.99%