IPGeolocation SDK

Ipgeolocation provides a set of APIs to make ip based decisions.

Supports IPGeolocation API version: 2.0
Package version: 1.0.0

Installation
Authentication
API Endpoints
IP Geolocation Examples
IP Security Examples
ASN API Examples
Timezone API Examples
Timezone Converter Examples
- Convert Current Time from One Timezone to Another
User Agent API Examples
- Parse a Basic User Agent String
- Bulk User Agent Parsing Example
Astronomy API Examples

Astronomy by Coordinates
Astronomy by IP Address
Astronomy by Location String
Astronomy for Specific Date
Astronomy in Different Language

Abuse Contact Api Examples

Lookup Abuse Contact by IP
Lookup Abuse Contact with Specific Fields
Lookup Abuse Contact while Excluding Fields

Documentation for Models

Installation

From RubyGems

Install via command line:

gem install ipgeolocation_sdk

Or add to your Gemfile:

gem 'ipgeolocation_sdk', '~> 1.0.0'

Then run:

bundle install

From Source (Local Build)

To build and install locally:

gem build ipgeolocation_sdk.gemspec
gem install ./ipgeolocation_sdk-1.0.0.gem

From GitHub

To install directly from a GitHub repository:

gem 'ipgeolocation_sdk', git: 'https://github.com/IPGeolocation/ip-geolocation-ruby-sdk.git'

Authentication

Please follow the installation procedure and then run the following code:

# Load the gem
require 'ipgeolocation_sdk'

# Setup authorization
IpgeolocationSdk.configure do |config|
  config.api_key['apiKey'] = 'YOUR API KEY'
end

API Endpoints

All URIs are relative to https://api.ipgeolocation.io/v2

Class	Method	HTTP request	Description
IpgeolocationSdk::ASNLookupApi	get_asn_info	GET /asn	Get details of any ASN number or associated IP address
IpgeolocationSdk::AbuseContactApi	get_abuse_contact_info	GET /abuse	Retrieve abuse reporting contact information for a given IP address
IpgeolocationSdk::AstronomyApi	get_astronomy_details	GET /astronomy	Get sunrise, sunset, moonrise, moonset, and related data for a location
IpgeolocationSdk::IPGeolocationApi	get_bulk_ip_geolocation	POST /ipgeo-bulk	Get geolocation data for multiple IP addresses in a single API request
IpgeolocationSdk::IPGeolocationApi	get_ip_geolocation	GET /ipgeo	Get geolocation data for a single IP address
IpgeolocationSdk::IPSecurityApi	get_bulk_ip_security_info	POST /security-bulk	Retrieve security threat intelligence for multiple IPs
IpgeolocationSdk::IPSecurityApi	get_ip_security_info	GET /security	Retrieve security threat intelligence for a single IP
IpgeolocationSdk::TimeConversionApi	convert_time_between_timezones	GET /timezone/convert	Convert time between two specified timezones
IpgeolocationSdk::TimezoneApi	get_timezone_info	GET /timezone	Timezone information details
IpgeolocationSdk::UserAgentApi	get_user_agent_details	GET /user-agent	Get details of user-agent
IpgeolocationSdk::UserAgentApi	parse_bulk_user_agent_strings	POST /user-agent-bulk	Handle multiple user-agent string lookups

Example Usage

IP Geolocation Examples

This section provides usage examples of the get_ip_geolocation() method from the SDK across Free, Standard, and Advanced subscription tiers. Each example highlights different combinations of parameters: fields, include, and excludes.

Parameters

`fields`

Use this parameter to include specific fields in the response.

`excludes`

Use this parameter to omit specific fields from the response.

`include`

Use this parameter to add optional modules to the response, such as:

security
user_agent
hostname
liveHostname
hostnameFallbackLive
abuse
dma
timezone

For complete details, refer to the official documentation: IP Geolocation API Documentation

The ip parameter in the SDK can accept any valid IPv4 address, IPv6 address, or domain name. If the ip() method is not used or the parameter is omitted, the API will return information about the public IP address of the device or server where the SDK is executed.

1. Developer (Free) Plan Examples

Default Fields

get_geolocation_opts = {
  ip: "8.8.8.8"
}
geolocation_instance = IpgeolocationSdk::IPGeolocationApi.new
begin 
    result = geolocation_instance.get_ip_geolocation(get_geolocation_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling GeolocationApi: #{e}"
end

Sample Response:

class GeolocationResponse {
    ip: 8.8.8.8
    location: class Location {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/us_64.png
        geonameId: 6301403
        countryEmoji: 🇺🇸
    }
    countryMetadata: class CountryMetadata {
        callingCode: +1
        tld: .us
        languages: [en-US, es-US, haw, fr]
    }
    currency: class Currency {
        code: USD
        name: US Dollar
        symbol: $
    }
}

Filtering Specific Fields from the Response (Use of 'exclude' and 'fields')

get_geolocation_opts = {
  ip: "8.8.4.4",
  fields: "location",
  excludes: "location.continent_code,location.continent_name"
}
geolocation_instance = IpgeolocationSdk::IPGeolocationApi.new
begin 
    result = geolocation_instance.get_ip_geolocation(get_geolocation_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling GeolocationApi: #{e}"
end

Sample Response

class GeolocationResponse {
    ip: 8.8.4.4
    location: class Location {
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/us_64.png
        geonameId: 6301403
        countryEmoji: 🇺🇸
    }
}

2. Standard Plan Examples

Default Fields

get_geolocation_opts = {
  ip: "8.8.8.8"
}
geolocation_instance = IpgeolocationSdk::IPGeolocationApi.new
begin 
    result = geolocation_instance.get_ip_geolocation(get_geolocation_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling GeolocationApi: #{e}"
end

Sample Response:

class GeolocationResponse {
    ip: 8.8.8.8
    location: class Location {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/us_64.png
        geonameId: 6301403
        countryEmoji: 🇺🇸
    }
    countryMetadata: class CountryMetadata {
        callingCode: +1
        tld: .us
        languages: [en-US, es-US, haw, fr]
    }
    network: class Network {
        asn: class NetworkAsn {
            asNumber: AS15169
            organization: Google LLC
            country: US
        }
        company: class NetworkCompany {
            name: Google LLC
        }
    }
    currency: class Currency {
        code: USD
        name: US Dollar
        symbol: $
    }
}

Retrieving Geolocation Data in Multiple Languages

Here is an example to get the geolocation data for IP address '2001:4230:4890::1' in French language:

get_geolocation_opts = {
  ip: "2001:4230:4890::1",
  lang: "fr"
}
geolocation_instance = IpgeolocationSdk::IPGeolocationApi.new
begin 
    result = geolocation_instance.get_ip_geolocation(get_geolocation_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling GeolocationApi: #{e}"
end

Sample Response

class GeolocationResponse {
    ip: 2001:4230:4890:0:0:0:0:1
    location: class Location {
        continentCode: AF
        continentName: Afrique
        countryCode2: MU
        countryCode3: MUS
        countryName: Maurice
        countryNameOfficial: 
        countryCapital: Port Louis
        stateProv: Wilhems des plaines
        stateCode: MU-PW
        district: Quatre Bornes
        city: Quatre Bornes
        zipcode: 72201
        latitude: -20.24304
        longitude: 57.49631
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/mu_64.png
        geonameId: 1106777
        countryEmoji: 🇲🇺
    }
    countryMetadata: class CountryMetadata {
        callingCode: +230
        tld: .mu
        languages: [en-MU, bho, fr]
    }
    network: class Network {
        asn: class NetworkAsn {
            asNumber: AS0
            organization: 
            country:
        }
        company: class NetworkCompany {
            name: African Network Information Center AfriNIC Ltd
        }
    }
    currency: class Currency {
        code: MUR
        name: Mauritius Rupee
        symbol: ₨
    }
}

Include HostName, Timezone and User-Agent

get_geolocation_opts = {
  ip: "4.5.6.7",
  include: "hostname,time_zone,user_agent"
}
geolocation_instance = IpgeolocationSdk::IPGeolocationApi.new
begin 
    result = geolocation_instance.get_ip_geolocation(get_geolocation_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling GeolocationApi: #{e}"
end

Sample Response

class GeolocationResponse {
    ip: 4.5.6.7
    hostname: 4.5.6.7
    location: class Location {
        countryName: United States
        countryCapital: Washington, D.C.
    }
    timeZone: class TimeZone {
        name: America/Chicago
        offset: -6
        offsetWithDst: -5
        currentTime: 2025-05-28 06:52:16.748-0500
        currentTimeUnix: 1748433136.748
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimeZoneDstStart {
            utcTime: 2025-03-09 TIME 08
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-09 TIME 03
            dateTimeBefore: 2025-03-09 TIME 02
            overlap: false
        }
        dstEnd: class TimeZoneDstEnd {
            utcTime: 2025-11-02 TIME 07
            duration: -1H
            gap: false
            dateTimeAfter: 2025-11-02 TIME 01
            dateTimeBefore: 2025-11-02 TIME 02
            overlap: true
        }
    }
    userAgent: class UserAgentData {
        userAgentString: IPGeolocation/2.0.0/java
        name: IPGeolocation Java SDK
        type: Special
        version: 2.0.0
        versionMajor: 1
        device: class UserAgentDataDevice {
            name: Unknown
            type: Unknown
            brand: Unknown
            cpu: Unknown
        }
        engine: class UserAgentDataEngine {
            name: Unknown
            type: Unknown
            version: ??
            versionMajor: ??
        }
        operatingSystem: class UserAgentDataOperatingSystem {
            name: Unknown
            type: Unknown
            version: ??
            versionMajor: ??
            build: ??
        }
    }
}

Note on Hostname Parameters

The IP Geolocation API supports hostname lookup for all paid subscriptions. However, this is not included by default. To enable hostname resolution, use the include parameter with one of the following options:

hostname: Performs a quick lookup using the internal hostname database. If no match is found, the IP is returned as-is. This is fast but may produce incomplete results.
liveHostname: Queries live sources for accurate hostname resolution. This may increase response time.
hostnameFallbackLive: Attempts the internal database first, and falls back to live sources if no result is found. This option provides a balance of speed and reliability.

3. Advanced Plan Examples

Include DMA, Abuse and Security

get_geolocation_opts = {
  ip: "8.8.8.8",
  include: "dma,abuse,security",
  excludes: "location.country_flag,location.country_emoji"
}
geolocation_instance = IpgeolocationSdk::IPGeolocationApi.new
begin 
    result = geolocation_instance.get_ip_geolocation(get_geolocation_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling GeolocationApi: #{e}"
end

Sample Response:

class GeolocationResponse {
    ip: 8.8.8.8
    location: class Location {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
        isEu: false
        countryFlag: null
        geonameId: 6301403
        countryEmoji: null
        accuracyRadius: 
        locality: Mountain View
        dmaCode: 807
    }
    countryMetadata: class CountryMetadata {
        callingCode: +1
        tld: .us
        languages: [en-US, es-US, haw, fr]
    }
    network: class Network {
        asn: class NetworkAsn {
            asNumber: AS15169
            organization: Google LLC
            country: US
            asnName: GOOGLE
            type: BUSINESS
            domain: about.google
            dateAllocated: 
            allocationStatus: assigned
            numOfIpv4Routes: 965
            numOfIpv6Routes: 104
            rir: ARIN
        }
        connectionType: 
        company: class NetworkCompany {
            name: Google LLC
            type: Business
            domain: googlellc.com
        }
    }
    currency: class Currency {
        code: USD
        name: US Dollar
        symbol: $
    }
    security: class Security {
        threatScore: 0
        isTor: false
        isProxy: false
        proxyType: 
        proxyProvider: 
        isAnonymous: false
        isKnownAttacker: false
        isSpam: false
        isBot: false
        isCloudProvider: false
        cloudProvider: 
    }
    abuse: class Abuse {
        route: 8.8.8.0/24
        country: 
        handle: ABUSE5250-ARIN
        name: Abuse
        organization: Abuse
        role: abuse
        kind: group
        address: 1600 Amphitheatre Parkway
        Mountain View
        CA
        94043
        United States
        emails: [[email protected]]
        phoneNumbers: [+1-650-253-0000]
    }
}

These examples demonstrate typical usage of the IP Geolocation API with different subscription tiers. Use fields to specify exactly which data to receive, include for optional data like security and user agent, and excludes to omit specific keys from the response.

Note: All features available in the Free plan are also included in the Standard and Advanced plans. Similarly, all features of the Standard plan are available in the Advanced plan.

Bulk IP Geolocation Example

The SDK also supports bulk IP geolocation requests using the get_bulk_ip_geolocation() method. All parameters like fields, include, and excludes can also be used in bulk requests.

post_geolocation_opts = {
    ips: ["8.8.8.8", "asdasd"],
    include: "security",
    excludes: "location.country_flag,location.country_emoji"
}
geolocation_instance = IpgeolocationSdk::IPGeolocationApi.new
begin 
    result = geolocation_instance.get_bulk_ip_geolocation(post_geolocation_opts)
    result.each do |item| 
        if IpgeolocationSdk::BulkIPGeolocation.is_success?(item) # GeolocationResponse
            p item.ip
        elsif IpgeolocationSdk::BulkIPGeolocation.is_error?(item) # ErrorResponse
            p item.message
        end
    end
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling GeolocationApi: #{e}"
end

IP Security Examples

This section provides usage examples of the get_ip_security_info() method from the SDK across various subscription tiers. Each example demonstrates different ways to query threat intelligence and risk metadata using parameters like fields, excludes, and optional modules.

For full API specifications, refer to the official IP Security API documentation.

Basic Request (Minimal Setup)

get_ip_security_opts = {
    ip: "2.56.188.34"
}
security_instance = IpgeolocationSdk::IPSecurityApi.new
begin 
    result = security_instance.get_ip_security_info(get_ip_security_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling GeolocationApi: #{e}"
end

Sample Response

class SecurityAPIResponse {
    ip: 2.56.188.34
    security: class Security {
        threatScore: 80
        isTor: false
        isProxy: true
        proxyType: VPN
        proxyProvider: Nord VPN
        isAnonymous: true
        isKnownAttacker: true
        isSpam: false
        isBot: false
        isCloudProvider: true
        cloudProvider: Packethub S.A.
    }
}

Include Multiple Optional Fields

get_ip_security_opts = {
    ip: "2.56.188.34",
    include: "location,network,currency,time_zone,user_agent,country_metadata,hostname"
}
security_instance = IpgeolocationSdk::IPSecurityApi.new
begin 
    result = security_instance.get_ip_security_info(get_ip_security_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling GeolocationApi: #{e}"
end

Sample Response

class SecurityAPIResponse {
    ip: 2.56.188.34
    hostname: 2.56.188.34
    security: class Security {
        threatScore: 80
        isTor: false
        isProxy: true
        proxyType: VPN
        proxyProvider: Nord VPN
        isAnonymous: true
        isKnownAttacker: true
        isSpam: false
        isBot: false
        isCloudProvider: true
        cloudProvider: Packethub S.A.
    }
    location: class LocationMinimal {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        countryCapital: Washington, D.C.
        stateProv: Texas
        stateCode: US-TX
        district: Dallas County
        city: Dallas
        zipcode: 75207
        latitude: 32.78916
        longitude: -96.82170
        isEu: false
        countryFlag: https://ipgeolocation.io/static/flags/us_64.png
        geonameId: 7181768
        countryEmoji: 🇺🇸
    }
    network: class NetworkMinimal {
        asn: class NetworkMinimalAsn {
            asNumber: AS62240
            organization: Clouvider Limited
            country: GB
        }
        company: class NetworkMinimalCompany {
            name: Packethub S.A.
        }
    }
    timeZone: class TimeZone {
        name: America/Chicago
        offset: -6
        offsetWithDst: -5
        currentTime: 2025-05-29 08:27:44.939-0500
        currentTimeUnix: 1748525264.939
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimeZoneDstStart {
            utcTime: 2025-03-09 TIME 08
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-09 TIME 03
            dateTimeBefore: 2025-03-09 TIME 02
            overlap: false
        }
        dstEnd: class TimeZoneDstEnd {
            utcTime: 2025-11-02 TIME 07
            duration: -1H
            gap: false
            dateTimeAfter: 2025-11-02 TIME 01
            dateTimeBefore: 2025-11-02 TIME 02
            overlap: true
        }
    }
    userAgent: class UserAgentData {
        userAgentString: IPGeolocation/2.0.0/java
        name: IPGeolocation Java SDK
        type: Special
        version: 2.0.0
        versionMajor: 1
        device: class UserAgentDataDevice {
            name: Unknown
            type: Unknown
            brand: Unknown
            cpu: Unknown
        }
        engine: class UserAgentDataEngine {
            name: Unknown
            type: Unknown
            version: ??
            versionMajor: ??
        }
        operatingSystem: class UserAgentDataOperatingSystem {
            name: Unknown
            type: Unknown
            version: ??
            versionMajor: ??
            build: ??
        }
    }
    countryMetadata: class CountryMetadata {
        callingCode: +1
        tld: .us
        languages: [en-US, es-US, haw, fr]
    }
    currency: class Currency {
        code: USD
        name: US Dollar
        symbol: $
    }
}

Request with Field Filtering

get_ip_security_opts = {
    ip: "195.154.221.54",
    fields: "security.is_tor,security.is_proxy,security.is_bot,security.is_spam"
}
security_instance = IpgeolocationSdk::IPSecurityApi.new
begin 
    result = security_instance.get_ip_security_info(get_ip_security_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling SecurityApi: #{e}"
end

Sample Response

class SecurityAPIResponse {
    ip: 195.154.221.54
    security: class Security {
        isTor: false
        isProxy: true
        isSpam: false
        isBot: false
    }
}

Bulk IP Security Request

The SDK also supports bulk IP Security requests using the get_bulk_ip_security_info() method. All parameters like fields, include, and excludes can also be used in bulk requests.

post_ip_security_opts = {
  ips: ["2.56.188.34","2.56.188.35"],
  include: "location,network",
  fields: "security.threat_score,location.country_name"
}

security_instance = IpgeolocationSdk::IPSecurityAPI.new
begin 
    result = security_instance.get_bulk_ip_security_info(post_ip_security_opts)
    result.each do |item|
        if IpgeolocationSdk::BulkIPSecurity.is_success?(item) # SecurityAPIResponse
            p item.ip
        elsif IpgeolocationSdk::BulkIPSecurity.is_error?(item) # ErrorResponse
            p item.message
        end
    end
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling SecurityApi: #{e}"
end

ASN API Examples

This section provides usage examples of the get_asn_info() method from the SDK. These methods allow developers to retrieve detailed ASN-level network data either by ASN number or by IP address. Note that ASN API is only available in the Advanced subscription plans.

Refer to the ASN API documentation for a detailed list of supported fields and behaviors.

Get ASN Information by IP Address

asn_opts = {
  ip: '8.8.8.8',
}
asn_instance = IpgeolocationSdk::ASNLookupApi.new
begin
  result = asn_instance.get_asn_info(asn_opts)
  p result
rescue IpgeolocationSdk::ApiError => e
  puts "Error calling ASNLookupApi: #{e}"
end

Sample Response

class ASNResponse {
    ip: 8.8.8.8
    asn: class ASNDetails {
        asNumber: AS15169
        organization: Google LLC
        country: US
        asnName: GOOGLE
        type: BUSINESS
        domain: about.google
        dateAllocated: 
        allocationStatus: assigned
        numOfIpv4Routes: 983
        numOfIpv6Routes: 104
        rir: ARIN
    }
}

Get ASN Information by ASN Number

asn_opts = {
  asn: 15169,
}
asn_instance = IpgeolocationSdk::ASNLookupApi.new
begin
  result = asn_instance.get_asn_info(asn_opts)
  p result
rescue IpgeolocationSdk::ApiError => e
  puts "Error calling ASNLookupApi: #{e}"
end

Sample Response

class ASNResponse {
    asn: class ASNDetails {
        asNumber: AS15169
        organization: Google LLC
        country: US
        asnName: GOOGLE
        type: BUSINESS
        domain: about.google
        dateAllocated: 
        allocationStatus: assigned
        numOfIpv4Routes: 983
        numOfIpv6Routes: 104
        rir: ARIN
    }
}

Combine All objects using Include

asn_opts = {
    asn: 12,
    include: "peers,downstreams,upstreams,routes,whois_response"
}
asn_instance = IpgeolocationSdk::ASNLookupApi.new
begin
  result = asn_instance.get_asn_info(asn_opts)
  p result
rescue IpgeolocationSdk::ApiError => e
  puts "Error calling ASNLookupApi: #{e}"
end

Sample Response

class ASNResponse {
    ip: null
    asn: class ASNDetails {
        asNumber: AS12
        organization: New York University
        country: US
        asnName: NYU-DOMAIN
        type: EDUCATION
        domain: nyu.edu
        dateAllocated: 
        allocationStatus: assigned
        numOfIpv4Routes: 11
        numOfIpv6Routes: 1
        rir: ARIN
        routes: [192.76.177.0/24, 216.165.96.0/20, 216.165.89.0/24, 216.165.0.0/18, 216.165.112.0/21, 128.122.0.0/16, 2607:f600::/32, 216.165.102.0/24, 216.165.64.0/19, 216.165.120.0/22, 192.86.139.0/24, 216.165.103.0/24]
        upstreams: [class ASNConnection {
            asNumber: AS3269
            description: Telecom Italia S.p.A.
            country: IT
        }, class ASNConnection {
            asNumber: AS8220
            description: COLT Technology Services Group Limited
            country: GB
        }, class ASNConnection {
            asNumber: AS286
            description: GTT Communications Inc.
            country: US
        }, class ASNConnection {
            asNumber: AS3257
            description: GTT Communications Inc.
            country: US
        }, class ASNConnection {
            asNumber: AS3754
            description: NYSERNet
            country: US
        }, class ASNConnection {
            asNumber: AS3356
            description: Level 3 Parent, LLC
            country: US
        }, class ASNConnection {
            asNumber: AS6461
            description: Zayo Bandwidth
            country: US
        }, class ASNConnection {
            asNumber: AS137
            description: Consortium GARR
            country: IT
        }]
        downstreams: [class ASNConnection {
            asNumber: AS394666
            description: NYU Langone Health
            country: US
        }, class ASNConnection {
            asNumber: AS54965
            description: Polytechnic Institute of NYU
            country: US
        }]
        peers: [class ASNConnection {
            asNumber: AS3269
            description: Telecom Italia S.p.A.
            country: IT
        }, class ASNConnection {
            asNumber: AS8220
            description: COLT Technology Services Group Limited
            country: GB
        }, class ASNConnection {
            asNumber: AS394666
            description: NYU Langone Health
            country: US
        }, class ASNConnection {
            asNumber: AS286
            description: GTT Communications Inc.
            country: NL
        }, class ASNConnection {
            asNumber: AS286
            description: GTT Communications Inc.
            country: US
        }, class ASNConnection {
            asNumber: AS3257
            description: GTT Communications Inc.
            country: US
        }, class ASNConnection {
            asNumber: AS3754
            description: NYSERNet
            country: US
        }, class ASNConnection {
            asNumber: AS3356
            description: Level 3 Parent, LLC
            country: US
        }, class ASNConnection {
            asNumber: AS6461
            description: Zayo Bandwidth
            country: US
        }, class ASNConnection {
            asNumber: AS137
            description: Consortium GARR
            country: IT
        }, class ASNConnection {
            asNumber: AS54965
            description: Polytechnic Institute of NYU
            country: US
        }]
        whoisResponse: 
        
        
        ASNumber:       12
        ASName:         NYU-DOMAIN
        ASHandle:       AS12
        RegDate:        1984-07-05
        Updated:        2023-05-25    
        Ref:            https://rdap.arin.net/registry/autnum/12
        
        
        OrgName:        New York University
        OrgId:          NYU-Z
        Address:        726 Broadway, 8th Floor - ITS
        City:           New York
        StateProv:      NY
        PostalCode:     10003
        Country:        US
        RegDate:        2023-05-15
        Updated:        2023-05-15
        Ref:            https://rdap.arin.net/registry/entity/NYU-Z
        
        
        OrgAbuseHandle: OIS9-ARIN
        OrgAbuseName:   Office of Information Security
        OrgAbusePhone:  +1-212-998-3333 
        OrgAbuseEmail:  [email protected]
        OrgAbuseRef:    https://rdap.arin.net/registry/entity/OIS9-ARIN
        
        OrgNOCHandle: COSI-ARIN
        OrgNOCName:   Communications Operations Services - ITS
        OrgNOCPhone:  +1-212-998-3444 
        OrgNOCEmail:  [email protected]
        OrgNOCRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
        
        OrgTechHandle: COSI-ARIN
        OrgTechName:   Communications Operations Services - ITS
        OrgTechPhone:  +1-212-998-3444 
        OrgTechEmail:  [email protected]
        OrgTechRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
        
        RTechHandle: COSI-ARIN
        RTechName:   Communications Operations Services - ITS
        RTechPhone:  +1-212-998-3444 
        RTechEmail:  [email protected]
        RTechRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
        
        RNOCHandle: COSI-ARIN
        RNOCName:   Communications Operations Services - ITS
        RNOCPhone:  +1-212-998-3444 
        RNOCEmail:  [email protected]
        RNOCRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
               
    }
}

Timezone API Examples

This section provides usage examples of the get_timezone_info() method from the SDK, showcasing how to fetch timezone and time-related data using different query types — IP address, latitude/longitude, and timezone ID.

For full API specifications, refer to the Timezone API documentation.

Get Timezone by IP Address

time_zone_opts = {
    ip: "8.8.8.8"
}
time_zone_instance = IpgeolocationSdk::TimezoneApi.new
begin 
    result = time_zone_instance.get_timezone_info(time_zone_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling TimezoneApi: #{e}"
end

Sample Response

class TimeZoneResponse {
    ip: 8.8.8.8
   
    location: class TimezoneLocation {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        isEu: false
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        locality: null
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
    }
    timeZone: class TimezoneDetails {
        name: America/Los_Angeles
        offset: -8
        offsetWithDst: -7
        date: 2025-06-23
        dateTime: 2025-06-23 02:15:25
        dateTimeTxt: Monday, June 23, 2025 02:15:25
        dateTimeWti: Mon, 23 Jun 2025 02:15:25 -0700
        dateTimeYmd: 2025-06-23T02:15:25-0700
        dateTimeUnix: 1.750670125437E9
        time24: 02:15:25
        time12: 02:15:25 AM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-09 TIME 10
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-09 TIME 03
            dateTimeBefore: 2025-03-09 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-11-02 TIME 09
            duration: -1H
            gap: false
            dateTimeAfter: 2025-11-02 TIME 01
            dateTimeBefore: 2025-11-02 TIME 02
            overlap: true
        }
    }
}

Get Timezone by Timezone Name

time_zone_opts = {
    tz: "Europe/London"
}
time_zone_instance = IpgeolocationSdk::TimezoneApi.new
begin 
    result = time_zone_instance.get_timezone_info(time_zone_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling TimezoneApi: #{e}"
end

Sample Response

class TimeZoneResponse {
    timeZone: class TimezoneDetails {
        name: Europe/London
        offset: 0
        offsetWithDst: 1
        date: 2025-06-23
        dateTime: 2025-06-23 10:25:01
        dateTimeTxt: Monday, June 23, 2025 10:25:01
        dateTimeWti: Mon, 23 Jun 2025 10:25:01 +0100
        dateTimeYmd: 2025-06-23T10:25:01+0100
        dateTimeUnix: 1.750670701706E9
        time24: 10:25:01
        time12: 10:25:01 AM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 02
            dateTimeBefore: 2025-03-30 TIME 01
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 01
            dateTimeBefore: 2025-10-26 TIME 02
            overlap: true
        }
    }
}

Get Timezone from Any Address

time_zone_opts = {
    location: "Munich, Germany"
}
time_zone_instance = IpgeolocationSdk::TimezoneApi.new
begin 
    result = time_zone_instance.get_timezone_info(time_zone_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling TimezoneApi: #{e}"
end

Sample Response

class TimeZoneResponse {
    location: class TimezoneLocation {
        locationString: Munich, Germany
        countryName: Germany
        stateProv: Bavaria
        city: Munich
        locality: 
        latitude: 48.13711
        longitude: 11.57538
    }
    timeZone: class TimezoneDetails {
        name: Europe/Berlin
        offset: 1
        offsetWithDst: 2
        date: 2025-06-23
        dateTime: 2025-06-23 11:35:23
        dateTimeTxt: Monday, June 23, 2025 11:35:23
        dateTimeWti: Mon, 23 Jun 2025 11:35:23 +0200
        dateTimeYmd: 2025-06-23T11:35:23+0200
        dateTimeUnix: 1.750671323755E9
        time24: 11:35:23
        time12: 11:35:23 AM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 03
            dateTimeBefore: 2025-03-30 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 02
            dateTimeBefore: 2025-10-26 TIME 03
            overlap: true
        }
    }
}

Get Timezone from Location Coordinates

time_zone_opts = {
    lat: 48.13711,
    long: 11.57538
}
time_zone_instance = IpgeolocationSdk::TimezoneApi.new
begin 
    result = time_zone_instance.get_timezone_info(time_zone_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling TimezoneApi: #{e}"
end

Sample Response

class TimeZoneResponse {
    timeZone: class TimezoneDetails {
        name: Europe/Paris
        offset: 1
        offsetWithDst: 2
        date: 2025-06-23
        dateTime: 2025-06-23 11:53:31
        dateTimeTxt: Monday, June 23, 2025 11:53:31
        dateTimeWti: Mon, 23 Jun 2025 11:53:31 +0200
        dateTimeYmd: 2025-06-23T11:53:31+0200
        dateTimeUnix: 1.750672411295E9
        time24: 11:53:31
        time12: 11:53:31 AM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 03
            dateTimeBefore: 2025-03-30 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 02
            dateTimeBefore: 2025-10-26 TIME 03
            overlap: true
        }
    }
}

Get Timezone and Airport Details from IATA Code

time_zone_opts = {
    iata_code: "ZRH"
}
time_zone_instance = IpgeolocationSdk::TimezoneApi.new
begin 
    result = time_zone_instance.get_timezone_info(time_zone_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling TimezoneApi: #{e}"
end

Sample Response

class TimeZoneResponse {
    airportDetails: class TimezoneAirport {
        type: large_airport
        name: Zurich Airport
        latitude: 47.45806
        longitude: 8.54806
        elevationFt: 1417
        continentCode: EU
        countryCode: CH
        stateCode: CH-ZH
        city: Zurich
        iataCode: ZRH
        icaoCode: LSZH
        faaCode: 
    }
    timeZone: class TimezoneDetails {
        name: Europe/Zurich
        offset: 1
        offsetWithDst: 2
        date: 2025-06-23
        dateTime: 2025-06-23 12:24:08
        dateTimeTxt: Monday, June 23, 2025 12:24:08
        dateTimeWti: Mon, 23 Jun 2025 12:24:08 +0200
        dateTimeYmd: 2025-06-23T12:24:08+0200
        dateTimeUnix: 1.750674248242E9
        time24: 12:24:08
        time12: 12:24:08 PM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 03
            dateTimeBefore: 2025-03-30 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 02
            dateTimeBefore: 2025-10-26 TIME 03
            overlap: true
        }
    }
}

Similarly, you can fetch Airport Details and Timezone from using any ICAO code as well

Get Timezone and City Details from UN/LOCODE

time_zone_opts = {
    lo_code: "ESBCN"
}
time_zone_instance = IpgeolocationSdk::TimezoneApi.new
begin 
    result = time_zone_instance.get_timezone_info(time_zone_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling TimezoneApi: #{e}"
end

Sample Response

class TimeZoneResponse {
    loCodeDetails: class TimezoneLocode {
        loCode: ESBCN
        city: Barcelona
        stateCode: 
        countryCode: ES
        countryName: 
        locationType: Port, Rail Terminal, Road Terminal, Airport, Postal Exchange
        latitude: 41.38289
        longitude: 2.17743
    }
    timeZone: class TimezoneDetails {
        name: Europe/Madrid
        offset: 1
        offsetWithDst: 2
        date: 2025-06-23
        dateTime: 2025-06-23 12:32:55
        dateTimeTxt: Monday, June 23, 2025 12:32:55
        dateTimeWti: Mon, 23 Jun 2025 12:32:55 +0200
        dateTimeYmd: 2025-06-23T12:32:55+0200
        dateTimeUnix: 1.750674775033E9
        time24: 12:32:55
        time12: 12:32:55 PM
        week: 26
        month: 6
        year: 2025
        yearAbbr: 25
        isDst: true
        dstSavings: 1
        dstExists: true
        dstStart: class TimezoneDetailDstStart {
            utcTime: 2025-03-30 TIME 01
            duration: +1H
            gap: true
            dateTimeAfter: 2025-03-30 TIME 03
            dateTimeBefore: 2025-03-30 TIME 02
            overlap: false
        }
        dstEnd: class TimezoneDetailDstEnd {
            utcTime: 2025-10-26 TIME 01
            duration: -1H
            gap: false
            dateTimeAfter: 2025-10-26 TIME 02
            dateTimeBefore: 2025-10-26 TIME 03
            overlap: true
        }
    }
}

Timezone Converter Examples

This section provides usage examples of the convert_time_between_timezones() method from the SDK. The Timezone Converter API allows you to convert a specific time from one timezone to another using timezone identifiers and optional date/time inputs.

For more details, refer to official documentation: Timezone Converter API.

Convert Current Time from One Timezone to Another

time_conversion_opts = {
    tz_to: 'Asia/Tokyo',
    tz_from: 'America/New_York',
    # lat_from: 24.8607,
    # long_from: 67.0011,
    # lat_to: 40.7128,
    # long_to: -74.0060,
    # location_from: 'Karachi',
    # location_to: 'New York',
    # icao_from: 'OPKC',
    # icao_to: 'KJFK',
    # iata_from: 'KHI',
    # iata_to: 'JFK',
    # locode_from: 'PKKHI',
    # locode_to: 'USNYC'
}
time_conversion_instance = IpgeolocationSdk::TimeConversionApi.new
begin
  result = time_conversion_instance.convert_time_between_timezones(time_conversion_opts)
  p result
rescue IpgeolocationSdk::ApiError => e
  puts "Error calling TimeConversionApi: #{e}"
end

Sample Response

class TimeConversionResponse {
    originalTime: 2024-12-08 11:00
    convertedTime: 2024-12-09 01:00:00
    diffHour: 14.0
    diffMin: 840
}

Similarly, you can convert time from any timezone to another timezone using location coordinates (Latitude and Longitude), location addresses, IATA codes, ICAO codes and UN/LOCODE.

User Agent API Examples

This section provides usage examples of the get_user_agent_details() method from the SDK. The User Agent API extracts and classifies information from user agent strings, including browser, engine, device, OS, and type metadata.

For full explanation, visit the User Agent API documentation.

Parse a Basic User Agent String

get_user_agent_opts = {
    user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/237.84.2.178 Safari/537.36'
}
user_agent_instance = IpgeolocationSdk::UserAgentApi.new
begin
    result = user_agent_instance.get_user_agent_details(get_user_agent_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling UserAgentApi: #{e}"
end

Sample Response

class UserAgentData {
    userAgentString: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36
    name: Chrome
    type: Browser
    version: 125
    versionMajor: 125
    device: class UserAgentDataDevice {
        name: Desktop
        type: Desktop
        brand: Unknown
        cpu: Intel x86_64
    }
    engine: class UserAgentDataEngine {
        name: Blink
        type: Browser
        version: 125
        versionMajor: 125
    }
    operatingSystem: class UserAgentDataOperatingSystem {
        name: Windows NT
        type: Desktop
        version: ??
        versionMajor: ??
        build: ??
    }
}

If you don't pass any userAgentString, the API will return the data of device's user agent.

Bulk User Agent Parsing Example

The SDK also supports bulk User Agent parsing using the parse_bulk_user_agent_strings() method. This allows parsing multiple user agent strings in a single request. All fields available in single-user-agent parsing are returned per entry.

post_user_agent_opts = {
    user_agents: ["Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/237.84.2.178 Safari/537.36","Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1"]
}
user_agent_instance = IpgeolocationSdk::UserAgentApi.new
begin 
    result = user_agent_instance.parse_bulk_user_agent_strings(post_user_agent_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling UserAgentApi: #{e}"
end

Astronomy API Examples

This section provides usage examples of the get_astronomy_details() method from the SDK, allowing developers to fetch sun and moon timings and position data based on coordinates, IP, or location string.

Refer to the official Astronomy API documentation for more details.

Astronomy by Coordinates

get_astronomy_opts = {
    lat: "40.7128",
    long: "-74.0060"
}
astronomy_instance = IpgeolocationSdk::AstronomyApi.new
begin 
    result = astronomy_instance.get_astronomy_details(get_astronomy_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling AstronomyApi: #{e}"
end

Sample Response

class AstronomyResponse {
    location: class AstronomyLocation {
        countryName:
        stateProv: New York
        city: New York
        locality: 
        latitude: 40.71280
        longitude: -74.00600
        elevation: 6.0
    }
    astronomy: class Astronomy {
        date: 2025-07-22
        currentTime: 05:34:17.046
        midNight: 01:02
        nightEnd: 03:48
        morning: class AstronomyMorning {
            astronomicalTwilightBegin: 03:48
            astronomicalTwilightEnd: 04:32
            nauticalTwilightBegin: 04:32
            nauticalTwilightEnd: 05:12
            civilTwilightBegin: 05:12
            civilTwilightEnd: 05:43
            blueHourBegin: 04:59
            blueHourEnd: 05:24
            goldenHourBegin: 05:24
            goldenHourEnd: 06:23
        }
        sunrise: 05:43
        sunset: 20:21
        evening: class AstronomyEvening {
            goldenHourBegin: 19:41
            goldenHourEnd: 20:40
            blueHourBegin: 20:40
            blueHourEnd: 21:05
            civilTwilightBegin: 20:21
            civilTwilightEnd: 20:52
            nauticalTwilightBegin: 20:52
            nauticalTwilightEnd: 21:31
            astronomicalTwilightBegin: 21:31
            astronomicalTwilightEnd: 22:16
        }
        nightBegin: 22:16
        sunStatus: -
        solarNoon: 13:02
        dayLength: 14:37
        sunAltitude: -2.4240905951150817
        sunDistance: 152012050.75662628
        sunAzimuth: 60.53270916713848
        moonPhase: WANING_CRESCENT
        moonrise: 02:48
        moonset: 19:10
        moonStatus: -
        moonAltitude: 26.687264834949556
        moonDistance: 369857.6483476412
        moonAzimuth: 74.22460131532307
        moonParallacticAngle: -56.08124322972331
        moonIlluminationPercentage: -7.41
        moonAngle: 328.4181377849406
    }
}

Astronomy by IP Address

get_astronomy_opts = {
    ip: "8.8.8.8"
}
astronomy_instance = IpgeolocationSdk::AstronomyApi.new
begin 
    result = astronomy_instance.get_astronomy_details(get_astronomy_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling AstronomyApi: #{e}"
end

Sample Response

class AstronomyResponse {
    ip: 8.8.8.8
    location: class AstronomyLocation {
        continentCode: NA
        continentName: North America
        countryCode2: US
        countryCode3: USA
        countryName: United States
        countryNameOfficial: United States of America
        isEu: false
        stateProv: California
        stateCode: US-CA
        district: Santa Clara
        city: Mountain View
        locality: Charleston Terrace
        zipcode: 94043-1351
        latitude: 37.42240
        longitude: -122.08421
        elevation: 3.0
    }
    astronomy: class Astronomy {
        date: 2025-07-22
        currentTime: 02:36:01.027
        midNight: 01:15
        nightEnd: 04:18
        morning: class AstronomyMorning {
            astronomicalTwilightBegin: 04:18
            astronomicalTwilightEnd: 04:58
            nauticalTwilightBegin: 04:58
            nauticalTwilightEnd: 05:35
            civilTwilightBegin: 05:35
            civilTwilightEnd: 06:04
            blueHourBegin: 05:23
            blueHourEnd: 05:47
            goldenHourBegin: 05:47
            goldenHourEnd: 06:42
        }
        sunrise: 06:04
        sunset: 20:24
        evening: class AstronomyEvening {
            goldenHourBegin: 19:46
            goldenHourEnd: 20:42
            blueHourBegin: 20:42
            blueHourEnd: 21:05
            civilTwilightBegin: 20:24
            civilTwilightEnd: 20:54
            nauticalTwilightBegin: 20:54
            nauticalTwilightEnd: 21:30
            astronomicalTwilightBegin: 21:30
            astronomicalTwilightEnd: 22:10
        }
        nightBegin: 22:10
        sunStatus: -
        solarNoon: 13:14
        dayLength: 14:20
        sunAltitude: -29.312204242565592
        sunDistance: 152012050.7566263
        sunAzimuth: 21.915241201213632
        moonPhase: WANING_CRESCENT
        moonrise: 03:23
        moonset: 19:16
        moonStatus: -
        moonAltitude: -6.780866431657464
        moonDistance: 369859.5847016905
        moonAzimuth: 45.928379972251605
        moonParallacticAngle: -40.47546867785306
        moonIlluminationPercentage: -7.40
        moonAngle: 328.43423626935555
    }
}

Astronomy by Location String

get_astronomy_opts = {
    location: "Milan, Italy"
}
astronomy_instance = IpgeolocationSdk::AstronomyApi.new
begin 
    result = astronomy_instance.get_astronomy_details(get_astronomy_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling AstronomyApi: #{e}"
end

Sample Response

class AstronomyResponse {
    location: class AstronomyLocation {
        locationString: Milan, Italy
        countryName: Italy
        stateProv: Lombardy
        city: Milan
        locality: 
        latitude: 45.46419
        longitude: 9.18963
        elevation: 122.0
    }
    astronomy: class Astronomy {
        date: 2025-07-22
        currentTime: 11:37:28.787
        midNight: 01:29
        nightEnd: 03:39
        morning: class AstronomyMorning {
            astronomicalTwilightBegin: 03:39
            astronomicalTwilightEnd: 04:35
            nauticalTwilightBegin: 04:35
            nauticalTwilightEnd: 05:21
            civilTwilightBegin: 05:21
            civilTwilightEnd: 05:54
            blueHourBegin: 05:06
            blueHourEnd: 05:35
            goldenHourBegin: 05:35
            goldenHourEnd: 06:40
        }
        sunrise: 05:54
        sunset: 21:04
        evening: class AstronomyEvening {
            goldenHourBegin: 20:19
            goldenHourEnd: 21:24
            blueHourBegin: 21:24
            blueHourEnd: 21:52
            civilTwilightBegin: 21:04
            civilTwilightEnd: 21:38
            nauticalTwilightBegin: 21:38
            nauticalTwilightEnd: 22:23
            astronomicalTwilightBegin: 22:23
            astronomicalTwilightEnd: 23:18
        }
        nightBegin: 23:18
        sunStatus: -
        solarNoon: 13:29
        dayLength: 15:10
        sunAltitude: 55.76507063803926
        sunDistance: 152012050.7566263
        sunAzimuth: 128.26574664275847
        moonPhase: WANING_CRESCENT
        moonrise: 02:36
        moonset: 19:49
        moonStatus: -
        moonAltitude: 72.39158071193661
        moonDistance: 369861.22005060845
        moonAzimuth: 197.31311454833428
        moonParallacticAngle: 13.735730743087668
        moonIlluminationPercentage: -7.39
        moonAngle: 328.44782327106236
    }
}

Astronomy for Specific Date

get_astronomy_opts = {
    date: "2025-01-01",
    lat: "-27.47000",
    long: "153.02000"
}
astronomy_instance = IpgeolocationSdk::AstronomyApi.new
begin 
    result = astronomy_instance.get_astronomy_details(get_astronomy_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling AstronomyApi: #{e}"
end

Sample Response

class AstronomyResponse {
    location: class AstronomyLocation {
        countryName: Australia
        stateProv: Queensland
        city: Brisbane
        locality: Brisbane
        latitude: -27.47000
        longitude: 153.02000
        elevation: 
    }
    astronomy: class Astronomy {
        date: 2025-01-01
        currentTime: 19:45:17.561
        midNight: 23:51
        nightEnd: 03:24
        morning: class AstronomyMorning {
            astronomicalTwilightBegin: 03:24
            astronomicalTwilightEnd: 03:57
            nauticalTwilightBegin: 03:57
            nauticalTwilightEnd: 04:29
            civilTwilightBegin: 04:29
            civilTwilightEnd: 04:56
            blueHourBegin: 04:19
            blueHourEnd: 04:40
            goldenHourBegin: 04:40
            goldenHourEnd: 05:30
        }
        sunrise: 04:56
        sunset: 18:46
        evening: class AstronomyEvening {
            goldenHourBegin: 18:12
            goldenHourEnd: 19:02
            blueHourBegin: 19:02
            blueHourEnd: 19:23
            civilTwilightBegin: 18:46
            civilTwilightEnd: 19:13
            nauticalTwilightBegin: 19:13
            nauticalTwilightEnd: 19:45
            astronomicalTwilightBegin: 19:45
            astronomicalTwilightEnd: 20:18
        }
        nightBegin: 20:18
        sunStatus: -
        solarNoon: 11:51
        dayLength: 13:50
        sunAltitude: -12.059617608402677
        sunDistance: 147102938.88036567
        sunAzimuth: 235.897971324645
        moonPhase: NEW_MOON
        moonrise: 05:42
        moonset: 20:08
        moonStatus: -
        moonAltitude: 4.6701693782344345
        moonDistance: 380596.5823950267
        moonAzimuth: 244.56945849604378
        moonParallacticAngle: 118.21976701203934
        moonIlluminationPercentage: 2.49
        moonAngle: 18.156495178599695
    }
}

Astronomy in Different Language

You can also get Astronomy Data in other languages as well. Only paid subscriptions can access this feature.

get_astronomy_opts = {
    ip: "1.1.1.1",
    lang: "fr"
}
astronomy_instance = IpgeolocationSdk::AstronomyApi.new
begin 
    result = astronomy_instance.get_astronomy_details(get_astronomy_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling AstronomyApi: #{e}"
end

Sample Response

class AstronomyResponse {
    ip: 1.1.1.1
    location: class AstronomyLocation {
        continentCode: OC
        continentName: Océanie
        countryCode2: AU
        countryCode3: AUS
        countryName: Australie
        countryNameOfficial: 
        isEu: false
        stateProv: Queensland
        stateCode: AU-QLD
        district: Brisbane
        city: Brisbane Sud
        locality: 
        zipcode: 4101
        latitude: -27.47306
        longitude: 153.01421
        elevation: 
    }
    astronomy: class Astronomy {
        date: 2025-07-22
        currentTime: 19:54:32.920
        midNight: 23:54
        nightEnd: 05:13
        morning: class AstronomyMorning {
            astronomicalTwilightBegin: 05:13
            astronomicalTwilightEnd: 05:41
            nauticalTwilightBegin: 05:41
            nauticalTwilightEnd: 06:09
            civilTwilightBegin: 06:09
            civilTwilightEnd: 06:34
            blueHourBegin: 06:00
            blueHourEnd: 06:19
            goldenHourBegin: 06:19
            goldenHourEnd: 07:08
        }
        sunrise: 06:34
        sunset: 17:14
        evening: class AstronomyEvening {
            goldenHourBegin: 16:40
            goldenHourEnd: 17:29
            blueHourBegin: 17:29
            blueHourEnd: 17:49
            civilTwilightBegin: 17:14
            civilTwilightEnd: 17:39
            nauticalTwilightBegin: 17:39
            nauticalTwilightEnd: 18:07
            astronomicalTwilightBegin: 18:07
            astronomicalTwilightEnd: 18:35
        }
        nightBegin: 18:35
        sunStatus: -
        solarNoon: 11:54
        dayLength: 10:39
        sunAltitude: -35.15165719378359
        sunDistance: 152012050.75662628
        sunAzimuth: 276.2757088601843
        moonPhase: WANING_CRESCENT
        moonrise: 04:04
        moonset: 14:19
        moonStatus: -
        moonAltitude: -66.8771626746063
        moonDistance: 369880.37618917384
        moonAzimuth: 278.66762618741274
        moonParallacticAngle: 93.79636599869248
        moonIlluminationPercentage: -7.32
        moonAngle: 328.6063710418327
    }
}

Abuse Contact API Examples

This section demonstrates how to use the get_abuse_contact_info() method of the AbuseContact API. This API helps security teams, hosting providers, and compliance professionals quickly identify the correct abuse reporting contacts for any IPv4 or IPv6 address. You can retrieve data like the responsible organization, role, contact emails, phone numbers, and address to take appropriate mitigation action against abusive or malicious activity.

Note: Abuse Contact API is only available in Advanced Plan

Refer to the official Abuse Contact API documentation for details on all available fields.

Lookup Abuse Contact by IP

abuse_opts = {
  ip: '1.0.0.0',
}
abuse_instance = IpgeolocationSdk::AbuseContactApi.new
begin 
    result = abuse_instance.get_abuse_contact_info(abuse_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling AbuseContactApi: #{e}"
end

Sample Response:

class AbuseResponse {
    ip: 1.0.0.0
    abuse: class Abuse {
        route: 1.0.0.0/24
        country: AU
        handle: IRT-APNICRANDNET-AU
        name: IRT-APNICRANDNET-AU
        organization: 
        role: abuse
        kind: group
        address: PO Box 3646
        South Brisbane, QLD 4101
        Australia
        emails: [[email protected]]
        phoneNumbers: [+61 7 3858 3100]
    }
}

Lookup Abuse Contact with Specific Fields

abuse_opts = {
  ip: '1.2.3.4',
  fields: 'abuse.role,abuse.emails',
}
abuse_instance = IpgeolocationSdk::AbuseContactApi.new
begin 
    result = abuse_instance.get_abuse_contact_info(abuse_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling AbuseContactApi: #{e}"
end

Sample Response:

class AbuseResponse {
    ip: 1.2.3.4
    abuse: class Abuse {
        role: abuse
        emails: [[email protected]]
    }
}

Lookup Abuse Contact while Excluding Fields

abuse_opts = {
  ip: '9.9.9.9',
  excludes: 'abuse.handle,abuse.emails',
}
abuse_instance = IpgeolocationSdk::AbuseContactApi.new
begin 
    result = abuse_instance.get_abuse_contact_info(abuse_opts)
    p result
rescue IpgeolocationSdk::ApiError => e
    puts "Error calling AbuseContactApi: #{e}"
end

Sample Response:

class AbuseResponse {
    ip: 9.9.9.9
    abuse: class Abuse {
        route: 9.9.9.0/24
        country:
        name: Quad9 Abuse
        organization: Quad9 Abuse
        role: abuse
        kind: group
        address: 1442 A Walnut Street Ste 501
        Berkeley
        CA
        94709
        United States
        phoneNumbers: [+1-415-831-3129]
    }
}

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
docs		docs
lib		lib
spec		spec
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.rspec		.rspec
.rubocop.yml		.rubocop.yml
.travis.yml		.travis.yml
Gemfile		Gemfile
LICENSE		LICENSE
README.md		README.md
Rakefile		Rakefile
git_push.sh		git_push.sh
ipgeolocation_sdk.gemspec		ipgeolocation_sdk.gemspec

License

IPGeolocation/ip-geolocation-ruby-sdk

Folders and files

Latest commit

History

Repository files navigation

IPGeolocation SDK

Table of Contents

Installation

From RubyGems

From Source (Local Build)

From GitHub

Authentication

API Endpoints

Example Usage

IP Geolocation Examples

Parameters

fields

excludes

include

1. Developer (Free) Plan Examples

Default Fields

2. Standard Plan Examples

Default Fields

Retrieving Geolocation Data in Multiple Languages

Include HostName, Timezone and User-Agent

3. Advanced Plan Examples

Include DMA, Abuse and Security

Bulk IP Geolocation Example

IP Security Examples

Basic Request (Minimal Setup)

Include Multiple Optional Fields

Request with Field Filtering

Bulk IP Security Request

ASN API Examples

Get ASN Information by IP Address

Get ASN Information by ASN Number

Combine All objects using Include

Timezone API Examples

Get Timezone by IP Address

Get Timezone by Timezone Name

Get Timezone from Any Address

Get Timezone from Location Coordinates

Get Timezone and Airport Details from IATA Code

Get Timezone and City Details from UN/LOCODE

Timezone Converter Examples

Convert Current Time from One Timezone to Another

User Agent API Examples

Parse a Basic User Agent String

Bulk User Agent Parsing Example

Astronomy API Examples

Astronomy by Coordinates

Astronomy by IP Address

Astronomy by Location String

Astronomy for Specific Date

Astronomy in Different Language

Abuse Contact API Examples

Lookup Abuse Contact by IP

Lookup Abuse Contact with Specific Fields

Lookup Abuse Contact while Excluding Fields

Documentation for Models

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

`fields`

`excludes`

`include`

Packages