API Reference

Hummingbird uses a simple, easy to integrate RESTful API for all endpoints.

Base URL

https://api.hummingbirdapi.com

Authentication

Include your API key in the X-API-Key header:

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

See Authentication for details.

Response Format

All responses use a unified envelope format with these fields in order:

Success

{
  "success": true,
  "data": { ... },
  "error": false,
  "error_code": null,
  "error_message": null
}

Error

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 20001,
  "error_message": "Missing API key"
}

Endpoints

Endpoint	Description
GET /v1/geo/lookup	IP geolocation

Versioning

Versions are specified in the URL path for the given API:

/v1/geo/lookup
     ^^

APIs are backwards compatible within major versions.

Examples

cURL

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

JavaScript

const response = await fetch(
  'https://api.hummingbirdapi.com/v1/geo/lookup',
  { headers: { 'X-API-Key': process.env.HUMMINGBIRD_API_KEY } }
);
const data = await response.json();

Python

import requests
import os

response = requests.get(
    'https://api.hummingbirdapi.com/v1/geo/lookup',
    headers={'X-API-Key': os.environ['HUMMINGBIRD_API_KEY']}
)
data = response.json()

Go

req, _ := http.NewRequest("GET",
    "https://api.hummingbirdapi.com/v1/geo/lookup", nil)
req.Header.Set("X-API-Key", os.Getenv("HUMMINGBIRD_API_KEY"))

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

var result GeoResponse
json.NewDecoder(resp.Body).Decode(&result)

Ruby

require 'httparty'

response = HTTParty.get(
  'https://api.hummingbirdapi.com/v1/geo/lookup',
  headers: { 'X-API-Key' => ENV['HUMMINGBIRD_API_KEY'] }
)
data = response.parsed_response

PHP

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

$data = $response->json();