Ruby

Get geolocation data in your Ruby application.

Prerequisites

• Ruby 2.7+
• A Hummingbird API key (get one free)

Installation

No gems required. Use the built-in net/http library or install HTTParty:

gem install httparty

Usage

Using net/http

require 'net/http'
require 'json'

uri = URI('https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8')
request = Net::HTTP::Get.new(uri)
request['X-API-Key'] = ENV['HUMMINGBIRD_API_KEY']

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

result = JSON.parse(response.body)

if result['success']
  data = result['data']
  location = data['location']
  time = data['time']
  currency = data['currency']
  puts "Location: #{location['city_name']}, #{location['country_name']}"
  puts "Timezone: #{time['zone']} (#{time['abbr']})"
  puts "Currency: #{currency['symbol']} #{currency['code']}"
  # Location: Mountain View, United States
  # Timezone: America/Los_Angeles (PST)
  # Currency: $ USD
end

Using HTTParty

require 'httparty'

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

if response['success']
  location = response['data']['location']
  puts "Country: #{location['country_name']}"
end

Look up visitor's IP

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

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

puts "Your IP: #{response['data']['ip']}"

Rails example

# app/controllers/locations_controller.rb
class LocationsController < ApplicationController
  def show
    client_ip = request.remote_ip

    response = HTTParty.get(
      'https://api.hummingbirdapi.com/v1/geo/lookup',
      query: { ip: client_ip },
      headers: { 'X-API-Key' => Rails.application.credentials.hummingbird_api_key }
    )

    render json: response.parsed_response
  end
end

Add to config/routes.rb:

get '/api/location', to: 'locations#show'

Sinatra example

require 'sinatra'
require 'httparty'

get '/api/location' do
  client_ip = request.ip

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

  content_type :json
  response.body
end

Error handling

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

result = response.parsed_response

unless result['success']
  puts "Error #{result['error_code']}: #{result['error_message']}"

  # Handle specific error codes
  case result['error_code']
  when 30001
    # Rate limit exceeded - wait and retry
  when 20001
    # Missing API key
  end
else
  puts result['data']
end

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
}

Next steps

• Authentication — Secure your API key
• Rate Limits — Understand request limits
• Error Handling — Handle errors gracefully
• IP Geolocation API Reference — Full endpoint documentation