Hummingbird

Appearance

cURL ​

Get geolocation data using cURL from the command line.

Prerequisites ​

  • cURL installed (included on most systems)
  • A Hummingbird API key (get one free)

Usage ​

Basic lookup ​

bash
curl -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8"

Look up your own IP ​

Omit the ip parameter to look up the caller's IP address:

bash
curl -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup"

Pretty print with jq ​

bash
curl -s -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8" | jq

Extract specific fields ​

bash
# Get just the country
curl -s -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8" | \
  jq -r '.data.location.country_name'
# United States

# Get city and region
curl -s -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8" | \
  jq -r '.data.location | "\(.city_name), \(.region_name)"'
# Mountain View, California

# Get timezone
curl -s -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8" | \
  jq -r '.data.time.zone'
# America/Los_Angeles

# Get currency
curl -s -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8" | \
  jq -r '.data.currency | "\(.symbol) \(.code)"'
# $ USD

Check for EU country ​

bash
curl -s -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8" | \
  jq -r 'if .data.location.country_is_eu then "EU country" else "Non-EU country" end'

Using environment variable ​

Set your API key as an environment variable:

bash
export HUMMINGBIRD_API_KEY="hb_live_xxxxx"

Then use it in requests:

bash
curl -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup"

Show response headers ​

bash
curl -i -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8"

Response headers include rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1706280000

Shell script example ​

bash
#!/bin/bash

lookup_ip() {
  local ip=$1
  curl -s -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
    "https://api.hummingbirdapi.com/v1/geo/lookup?ip=$ip"
}

# Look up multiple IPs
for ip in "8.8.8.8" "1.1.1.1" "208.67.222.222"; do
  echo "=== $ip ==="
  lookup_ip "$ip" | jq -r '.data | "\(.location.city_name), \(.location.country_name) | \(.time.zone) | \(.currency.symbol)"'
done

Error handling in bash ​

bash
#!/bin/bash

response=$(curl -s -H "X-API-Key: $HUMMINGBIRD_API_KEY" \
  "https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8")

success=$(echo "$response" | jq -r '.success')

if [ "$success" = "true" ]; then
  echo "$response" | jq '.data'
else
  error_code=$(echo "$response" | jq -r '.error_code')
  error_msg=$(echo "$response" | jq -r '.error_message')
  echo "Error $error_code: $error_msg" >&2
  exit 1
fi

Response ​

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

json
{
  "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
}

Next steps ​

Built with VitePress

Copyright © 2024-present Hummingbird