ipgeolocation_sdk 1.0.0 → 2.0.0

data/README.md

@@ -1,69 +1,42 @@
-# IPGeolocation SDK
+# IPGeolocation Ruby SDK
 
-Ipgeolocation provides a set of APIs to make ip based decisions.
+Official Ruby SDK for the IPGeolocation.io IP Location API.
 
+Look up IPv4, IPv6, and domains with `/v3/ipgeo` and `/v3/ipgeo-bulk`. Get geolocation, company, ASN, timezone, network, hostname, abuse, user-agent, and security data from one API.
 
-- Supports IPGeolocation API version: 2.0
-- Package version: 1.0.0
+- Ruby 2.7+
+- Sync client built on `Net::HTTP`
+- Typed responses plus raw JSON and XML methods
 
 ## Table of Contents
 
-1. [Installation](#installation)
-2. [Authentication](#authentication)
-3. [API Endpoints](#api-endpoints)
-4. [IP Geolocation Examples](#ip-geolocation-examples)
-   - [1. Developer (Free) Plan Examples](#1-developer-free-plan-examples)
-   - [2. Standard Plan Examples](#2-standard-plan-examples)
-   - [3. Advanced Plan Examples](#3-advanced-plan-examples)
-   - [Bulk IP Geolocation Example](#bulk-ip-geolocation-example)
-5. [IP Security Examples](#ip-security-examples)
-   - [Basic Request (Minimal Setup)](#basic-request-minimal-setup)
-   - [Include Multiple Optional Fields](#include-multiple-optional-fields)
-   - [Request with Field Filtering](#request-with-field-filtering)
-   - [Bulk IP Security Request](#bulk-ip-security-request)
-
-6. [ASN API Examples](#asn-api-examples)
-   - [Get ASN Information by IP Address](#get-asn-information-by-ip-address)
-   - [Get ASN Information by ASN Number](#get-asn-information-by-asn-number)
-   - [Combine All objects using Include](#combine-all-objects-using-include)
-
-7. [Timezone API Examples](#timezone-api-examples)
-   - [Get Timezone by IP Address](#get-timezone-by-ip-address)
-   - [Get Timezone by Timezone Name](#get-timezone-by-timezone-name)
-   - [Get Timezone from Any Address](#get-timezone-from-any-address)
-   - [Get Timezone from Location Coordinates](#get-timezone-from-location-coordinates)
-   - [Get Timezone and Airport Details from IATA Code](#get-timezone-and-airport-details-from-iata-code)
-   - [Get Timezone and City Details from UN/LOCODE](#get-timezone-and-city-details-from-unlocode)
-
-8. [Timezone Converter Examples](#timezone-converter-examples)
-   - [Convert Current Time from One Timezone to Another](#convert-current-time-from-one-timezone-to-another)
-
-9. [User Agent API Examples](#user-agent-api-examples)
-   - [Parse a Basic User Agent String](#parse-a-basic-user-agent-string)
-   - [Bulk User Agent Parsing Example](#bulk-user-agent-parsing-example)
-10. [Astronomy API Examples](#astronomy-api-examples)
-   - [Astronomy by Coordinates](#astronomy-by-coordinates)
-   - [Astronomy by IP Address](#astronomy-by-ip-address)
-   - [Astronomy by Location String](#astronomy-by-location-string)
-   - [Astronomy for Specific Date](#astronomy-for-specific-date)
-   - [Astronomy in Different Language](#astronomy-in-different-language)
-
-11. [Documentation for Models](#documentation-for-models)
-
-## Installation
-
-### From RubyGems
-
-Install via command line:
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [At a Glance](#at-a-glance)
+- [Get Your API Key](#get-your-api-key)
+- [Authentication](#authentication)
+- [Plan Behavior](#plan-behavior)
+- [Client Configuration](#client-configuration)
+- [Available Methods](#available-methods)
+- [Request Options](#request-options)
+- [Examples](#examples)
+- [Response Metadata](#response-metadata)
+- [JSON Helpers](#json-helpers)
+- [Errors](#errors)
+- [Troubleshooting](#troubleshooting)
+- [Frequently Asked Questions](#frequently-asked-questions)
+- [Links](#links)
+
+## Install
 
 ```bash
-gem install ipgeolocation
+gem install ipgeolocation_sdk
 ```
 
-Or add to your `Gemfile`:
+Or add it to your `Gemfile`:
 
 ```ruby
-gem 'ipgeolocation', '~> 1.0.0'
+gem "ipgeolocation_sdk", "~> 2.0"
 ```
 
 Then run:
@@ -72,2053 +45,365 @@ Then run:
 bundle install
 ```
 
----
-
-### From Source (Local Build)
-
-To build and install locally:
-
-```bash
-gem build ipgeolocation.gemspec
-gem install ./ipgeolocation-1.0.0.gem
+```ruby
+require "ipgeolocation_sdk"
 ```
 
----
-
-### From GitHub
+RubyGems package: `ipgeolocation_sdk`  
+Package page: <https://rubygems.org/gems/ipgeolocation_sdk>  
+GitHub repository: <https://github.com/IPGeolocation/ip-geolocation-ruby-sdk>
 
-To install directly from a GitHub repository:
+## Quick Start
 
 ```ruby
-gem 'ipgeolocation', git: 'https://github.com/IPGeolocation/ip-geolocation-ruby-sdk.git'
-```
-
-## Authentication
+require "ipgeolocation_sdk"
 
-Please follow the [installation](#installation) procedure and then run the following code:
+client = IpgeolocationSdk::IpGeolocationClient.new(
+  api_key: ENV.fetch("IPGEO_API_KEY")
+)
 
-```ruby
-# Load the gem
-require 'ipgeolocation_sdk'
+begin
+  response = client.lookup_ip_geolocation(ip: "8.8.8.8")
 
-# Setup authorization
-IpgeolocationSdk.configure do |config|
-  config.api_key['apiKey'] = 'YOUR API KEY'
+  puts response.data.ip # 8.8.8.8
+  puts response.data.location&.country_name # United States
+  puts response.data.location&.city
+  puts response.data.time_zone&.name
+  puts response.metadata.credits_charged
+ensure
+  client.close
 end
 ```
 
-## API Endpoints
+You can also pass `LookupIpGeolocationRequest` and `BulkLookupIpGeolocationRequest` objects if you want validation before the request is sent.
 
-All URIs are relative to *https://api.ipgeolocation.io/v2*
+## At a Glance
 
-Class | Method | HTTP request | Description
------------- | ------------- | ------------- | -------------
-*IpgeolocationSdk::ASNLookupApi* | [**get_asn_info**](docs/ASNLookupApi.md#get_asn_info) | **GET** /asn | Get details of any ASN number or associated IP address
-*IpgeolocationSdk::AbuseContactApi* | [**get_abuse_contact_info**](docs/AbuseContactApi.md#get_abuse_contact_info) | **GET** /abuse | Retrieve abuse reporting contact information for a given IP address
-*IpgeolocationSdk::AstronomyApi* | [**get_astronomy_details**](docs/AstronomyApi.md#get_astronomy_details) | **GET** /astronomy | Get sunrise, sunset, moonrise, moonset, and related data for a location
-*IpgeolocationSdk::IPGeolocationAPI* | [**get_bulk_ip_geolocation**](docs/IPLocationApi.md#get_bulk_ip_geolocation) | **POST** /ipgeo-bulk | Get geolocation data for multiple IP addresses in a single API request
-*IpgeolocationSdk::IPGeolocationAPI* | [**get_ip_geolocation**](docs/IPLocationApi.md#get_ip_geolocation) | **GET** /ipgeo | Get geolocation data for a single IP address
-*IpgeolocationSdk::IPSecurityApi* | [**get_bulk_ip_security_info**](docs/SecurityApi.md#get_bulk_ip_security_info) | **POST** /security-bulk | Retrieve security threat intelligence for multiple IPs
-*IpgeolocationSdk::IPSecurityApi* | [**get_ip_security_info**](docs/SecurityApi.md#get_ip_security_info) | **GET** /security |  Retrieve security threat intelligence for a single IP
-*IpgeolocationSdk::TimeConversionApi* | [**convert_time_between_timezones**](docs/TimeConversionApi.md#convert_time_between_timezones) | **GET** /timezone/convert |  Convert time between two specified timezones
-*IpgeolocationSdk::TimezoneApi* | [**get_timezone_info**](docs/TimezoneApi.md#get_timezone_info) | **GET** /timezone | Timezone information details
-*IpgeolocationSdk::UserAgentApi* | [**get_user_agent_details**](docs/UserAgentApi.md#get_user_agent_details) | **GET** /user-agent | Get details of user-agent
-*IpgeolocationSdk::UserAgentApi* | [**parse_bulk_user_agent_strings**](docs/UserAgentApi.md#parse_bulk_user_agent_strings) | **POST** /user-agent-bulk | Handle multiple user-agent string lookups
+| Item | Value |
+|------|-------|
+| Gem | `ipgeolocation_sdk` |
+| Module | `IpgeolocationSdk` |
+| Supported Endpoints | `/v3/ipgeo`, `/v3/ipgeo-bulk` |
+| Supported Inputs | IPv4, IPv6, domain |
+| Main Data Returned | Geolocation, company, ASN, timezone, network, hostname, abuse, user-agent, currency, security |
+| Authentication | API key, request-origin auth for `/v3/ipgeo` only |
+| Response Formats | Structured JSON, raw JSON, raw XML |
+| Bulk Limit | Up to 50,000 IPs or domains per request |
+| Transport | `Net::HTTP` |
 
+## Get Your API Key
 
-# Example Usage
+To use most SDK features, create or access your IPGeolocation account and copy an API key from your dashboard.
 
-## IP Geolocation Examples
+1. Sign up: <https://app.ipgeolocation.io/signup>
+2. Verify your email if prompted
+3. Sign in: <https://app.ipgeolocation.io/login>
+4. Open your dashboard: <https://app.ipgeolocation.io/dashboard>
+5. Copy an API key from the `API Keys` section
 
-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](https://ipgeolocation.io/ip-location-api.html#documentation-overview)
-
-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.
+For server-side code, keep the API key in an environment variable or secret manager. For browser-based single lookups on paid plans, use request-origin auth instead of exposing an API key in frontend code.
 
+## Authentication
 
-### 1. Developer (Free) Plan Examples
-#### Default Fields
+### API Key
 
 ```ruby
-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')
-```ruby
-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: 🇺🇸
-    }
-}
+client = IpgeolocationSdk::IpGeolocationClient.new(
+  api_key: ENV.fetch("IPGEO_API_KEY")
+)
 ```
-### 2. Standard Plan Examples
-#### Default Fields
+
+### Request-Origin Auth
 
 ```ruby
-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:
-```ruby
-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
+client = IpgeolocationSdk::IpGeolocationClient.new(
+  request_origin: "https://app.example.com"
+)
 ```
 
-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: ₨
-    }
-}
-```
+`request_origin` must be an absolute `http` or `https` origin with no path, query string, fragment, or userinfo.
 
-#### Include HostName, Timezone and User-Agent
-```ruby
-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**
+> [!IMPORTANT]
+> Request-origin auth does not work with `/v3/ipgeo-bulk`. Bulk lookup always requires `api_key`.
 
-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:
+> [!NOTE]
+> If you set both `api_key` and `request_origin`, single lookup still uses the API key. The API key is sent as the `apiKey` query parameter, so avoid logging full request URLs.
 
-- `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.
+## Plan Behavior
 
-### 3. Advanced Plan Examples
-#### Include DMA, Abuse and Security
+Feature availability depends on your plan and request parameters.
 
-```ruby
-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: [network-abuse@google.com]
-        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.
+| Capability | Free | Paid |
+|------------|------|------|
+| Single IPv4 and IPv6 lookup | Supported | Supported |
+| Domain lookup | Not supported | Supported |
+| Bulk lookup | Not supported | Supported |
+| Non-English `lang` | Not supported | Supported |
+| Request-origin auth | Not supported | Supported for `/v3/ipgeo` only |
+| Optional modules via `include` | Not supported | Supported |
+| `include: ["*"]` | Base response only | All plan-available modules |
 
-**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.
+Paid plans still need `include` for optional modules. `fields` and `excludes` only trim the response. They do not turn modules on or unlock paid data.
 
-## 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.
+## Client Configuration
 
-```ruby
-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
-```
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `api_key` | `String` | unset | Required for bulk lookup. Optional for single lookup if `request_origin` is set. |
+| `request_origin` | `String` | unset | Must be an absolute `http` or `https` origin. |
+| `base_url` | `String` | `https://api.ipgeolocation.io` | Override the API base URL. |
+| `connect_timeout` | `Numeric` | `10.0` | Time to open the connection, in seconds. |
+| `read_timeout` | `Numeric` | `30.0` | Time to wait while reading the response body, in seconds. |
 
-## IP Security Examples
+The client constructor accepts either an `IpGeolocationClientConfig` or a hash with the same keys.
 
-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.
+## Available Methods
 
-For full API specifications, refer to the [official IP Security API documentation](https://ipgeolocation.io/ip-security-api.html#documentation-overview).
+| Method | Returns | Notes |
+|--------|---------|-------|
+| `lookup_ip_geolocation(request = nil)` | `ApiResponse` with typed `data` | Single lookup. Typed JSON response. |
+| `lookup_ip_geolocation_raw(request = nil)` | `ApiResponse` with `String` `data` | Single lookup. Raw JSON or XML string. |
+| `bulk_lookup_ip_geolocation(request)` | `ApiResponse` with bulk result array | Bulk lookup. Typed JSON response. |
+| `bulk_lookup_ip_geolocation_raw(request)` | `ApiResponse` with `String` `data` | Bulk lookup. Raw JSON or XML string. |
+| `close` | `nil` | Closes the client. Do not reuse the client after this. |
 
----
+> [!NOTE]
+> Typed methods support JSON only. Use the raw methods when you need XML output.
 
-### Basic Request (Minimal Setup)
+## Request Options
 
-```ruby
-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
-```
+| Field | Applies To | Notes |
+|-------|------------|-------|
+| `ip` | Single lookup | IPv4, IPv6, or domain. Omit it for caller IP lookup. |
+| `ips` | Bulk lookup | Array of 1 to 50,000 IPs or domains. |
+| `lang` | Single and bulk | One of `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`. |
+| `include` | Single and bulk | Array of module names such as `security`, `abuse`, `user_agent`, `hostname`, `liveHostname`, `hostnameFallbackLive`, `geo_accuracy`, `dma_code`, or `*`. |
+| `fields` | Single and bulk | Array of field paths to keep, for example `["location.country_name", "security.threat_score"]`. |
+| `excludes` | Single and bulk | Array of field paths to remove from the response. |
+| `user_agent` | Single and bulk | Overrides the outbound `User-Agent` header. |
+| `headers` | Single and bulk | Extra request headers. Use a hash where each value is a string or an array of strings. |
+| `output` | Single and bulk | `"json"` or `"xml"`. Typed methods require JSON. |
 
-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
-```ruby
-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
-```
+## Examples
 
-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
+The examples below assume you already have a configured client in scope:
 
 ```ruby
-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
+client = IpgeolocationSdk::IpGeolocationClient.new(
+  api_key: ENV.fetch("IPGEO_API_KEY")
+)
 ```
-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.
+### Caller IP
+
+Omit `ip` to look up the public IP of the machine making the request.
 
 ```ruby
-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
+response = client.lookup_ip_geolocation
+puts response.data.ip
 ```
 
-## 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.
+### Domain Lookup
 
-Refer to the [ASN API documentation](https://ipgeolocation.io/asn-api.html#documentation-overview) for a detailed list of supported fields and behaviors.
-
-### Get ASN Information by IP Address
+Domain lookup is a paid-plan feature.
 
 ```ruby
-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
+response = client.lookup_ip_geolocation(ip: "ipgeolocation.io")
 
+puts response.data.ip
+puts response.data.domain # ipgeolocation.io
+puts response.data.location&.country_name
 ```
-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
 
-```ruby
-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
-    }
-}
-```
+### Security and Abuse
 
-### Combine All objects using Include
 ```ruby
-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:  abuse@nyu.edu
-        OrgAbuseRef:    https://rdap.arin.net/registry/entity/OIS9-ARIN
-        
-        OrgNOCHandle: COSI-ARIN
-        OrgNOCName:   Communications Operations Services - ITS
-        OrgNOCPhone:  +1-212-998-3444 
-        OrgNOCEmail:  noc-cosi-arin@nyu.edu
-        OrgNOCRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
-        
-        OrgTechHandle: COSI-ARIN
-        OrgTechName:   Communications Operations Services - ITS
-        OrgTechPhone:  +1-212-998-3444 
-        OrgTechEmail:  noc-cosi-arin@nyu.edu
-        OrgTechRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
-        
-        RTechHandle: COSI-ARIN
-        RTechName:   Communications Operations Services - ITS
-        RTechPhone:  +1-212-998-3444 
-        RTechEmail:  noc-cosi-arin@nyu.edu
-        RTechRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
-        
-        RNOCHandle: COSI-ARIN
-        RNOCName:   Communications Operations Services - ITS
-        RNOCPhone:  +1-212-998-3444 
-        RNOCEmail:  noc-cosi-arin@nyu.edu
-        RNOCRef:    https://rdap.arin.net/registry/entity/COSI-ARIN
-               
-    }
-}
+response = client.lookup_ip_geolocation(
+  ip: "9.9.9.9",
+  include: ["security", "abuse"]
+)
+
+puts response.data.security&.threat_score
+puts response.data.abuse&.emails&.first
 ```
 
-## Timezone API Examples
+### User-Agent Parsing
 
-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.
+To parse a visitor user-agent string, pass `include: ["user_agent"]` and send the visitor string in the request `User-Agent` header.
 
-For full API specifications, refer to the [Timezone API documentation](https://ipgeolocation.io/timezone-api.html#documentation-overview).
+```ruby
+visitor_ua = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"
 
-### Get Timezone by IP Address
+response = client.lookup_ip_geolocation(
+  ip: "115.240.90.163",
+  include: ["user_agent"],
+  headers: { "User-Agent" => visitor_ua }
+)
 
-```ruby
-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
-        }
-    }
-}
+puts response.data.user_agent&.name
+puts response.data.user_agent&.operating_system&.name
 ```
-### Get Timezone by Timezone Name
 
-```ruby
-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
+> [!NOTE]
+> The `user_agent` request field overrides the SDK's default outbound `User-Agent` header. It takes precedence over `headers["User-Agent"]`.
 
-```ruby
-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
+### Filtered Response
 
 ```ruby
-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
+response = client.lookup_ip_geolocation(
+  ip: "8.8.8.8",
+  include: ["security"],
+  fields: ["location.country_name", "security.threat_score", "security.is_vpn"],
+  excludes: ["currency"]
+)
 
-```ruby
-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
-        }
-    }
-}
+puts response.data.location&.country_name
+puts response.data.security&.threat_score
+puts response.data.security&.is_vpn
 ```
-Similarly, you can fetch Airport Details and Timezone from using any ICAO code as well
 
-### Get Timezone and City Details from UN/LOCODE
+### Raw XML
 
 ```ruby
-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
-        }
-    }
-}
-```
+response = client.lookup_ip_geolocation_raw(
+  ip: "8.8.8.8",
+  output: IpgeolocationSdk::ResponseFormat::XML
+)
 
-## Timezone Converter Examples
+puts response.data
+```
 
-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.
+### Bulk Lookup
 
-For more details, refer to official documentation: [Timezone Converter API](https://ipgeolocation.io/timezone-api.html#convert-time-bw-time-zones).
+Bulk lookup is a paid-plan feature and always requires `api_key`.
 
-### Convert Current Time from One Timezone to Another
+Each bulk result is either a success or an error.
 
 ```ruby
-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.
+response = client.bulk_lookup_ip_geolocation(
+  ips: ["8.8.8.8", "invalid-ip", "1.1.1.1"],
+  include: ["security"]
+)
 
-## User Agent API Examples
+response.data.each do |result|
+  if result.success?
+    puts result.data.ip
+    puts result.data.security&.threat_score
+    next
+  end
 
-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.
+  puts result.error.message
+end
+```
 
-For full explanation, visit the [User Agent API documentation](https://ipgeolocation.io/user-agent-api.html#documentation-overview).
+## Response Metadata
 
-### Parse a Basic User Agent String
+Each method returns an `ApiResponse` with `data` and `metadata`.
 
-```ruby
-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.
+`metadata` includes:
 
-## Bulk User Agent Parsing Example
+| Field | Meaning |
+|-------|---------|
+| `credits_charged` | Credits charged for the request when the API returns that header |
+| `successful_records` | Number of successful bulk records when the API returns that header |
+| `status_code` | HTTP status code |
+| `duration_ms` | Client-side request time in milliseconds |
+| `raw_headers` | Response headers as `Hash<String, Array<String>>` |
 
-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.
+Helper methods:
 
 ```ruby
-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
-```
+metadata = response.metadata
 
-## 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.
+puts metadata.status_code
+puts metadata.duration_ms
+puts metadata.header_values("X-Credits-Charged").inspect
+puts metadata.first_header_value("Content-Type")
+```
 
-Refer to the [official Astronomy API documentation](https://ipgeolocation.io/astronomy-api.html#documentation-overview) for more details.
+## JSON Helpers
 
-### Astronomy by Coordinates
+Use these helpers to turn SDK objects into JSON:
 
 ```ruby
-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
-```ruby
-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
-    }
-}
+puts IpgeolocationSdk.to_json(response.data)
+puts IpgeolocationSdk.to_pretty_json(response.data)
+puts IpgeolocationSdk.to_pretty_json(response.data, :full)
 ```
 
-### Astronomy by Location String
-```ruby
-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
-```ruby
-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
-    }
-}
-```
+Compact mode omits `nil` fields. Full mode keeps them.
 
-### Astronomy in Different Language
-You can also get Astronomy Data in other languages as well. Only paid subscriptions can access this feature.
-```ruby
-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
+## Errors
 
-Refer to the official [Abuse Contact API documentation](https://ipgeolocation.io/ip-abuse-contact-api.html#documentation-overview) for details on all available fields.
-### Lookup Abuse Contact by IP
-```ruby
-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: [helpdesk@apnic.net]
-        phoneNumbers: [+61 7 3858 3100]
-    }
-}
-```
+The SDK raises these exception classes:
 
-### Lookup Abuse Contact with Specific Fields
-```ruby
-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: [helpdesk@apnic.net]
-    }
-}
-```
-### Lookup Abuse Contact while Excluding Fields
-```ruby
-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]
-    }
-}
-```
+- `IpgeolocationSdk::ValidationError`
+- `IpgeolocationSdk::SerializationError`
+- `IpgeolocationSdk::TransportError`
+- `IpgeolocationSdk::RequestTimeoutError`
+- `IpgeolocationSdk::ApiError`
+- `IpgeolocationSdk::BadRequestError`
+- `IpgeolocationSdk::UnauthorizedError`
+- `IpgeolocationSdk::NotFoundError`
+- `IpgeolocationSdk::MethodNotAllowedError`
+- `IpgeolocationSdk::PayloadTooLargeError`
+- `IpgeolocationSdk::UnsupportedMediaTypeError`
+- `IpgeolocationSdk::LockedError`
+- `IpgeolocationSdk::RateLimitError`
+- `IpgeolocationSdk::ClientClosedRequestError`
+- `IpgeolocationSdk::ServerError`
 
-## Documentation for Models
-
- - [IpgeolocationSdk::ASNConnection](docs/ASNConnection.md)
- - [IpgeolocationSdk::ASNResponse](docs/ASNResponse.md)
- - [IpgeolocationSdk::ASNDetails](docs/ASNDetails.md)
- - [IpgeolocationSdk::Abuse](docs/Abuse.md)
- - [IpgeolocationSdk::AbuseResponse](docs/AbuseResponse.md)
- - [IpgeolocationSdk::Astronomy](docs/Astronomy.md)
- - [IpgeolocationSdk::AstronomyEvening](docs/AstronomyEvening.md)
- - [IpgeolocationSdk::AstronomyLocation](docs/AstronomyLocation.md)
- - [IpgeolocationSdk::AstronomyMorning](docs/AstronomyMorning.md)
- - [IpgeolocationSdk::AstronomyResponse](docs/AstronomyResponse.md)
- - [IpgeolocationSdk::CountryMetadata](docs/CountryMetadata.md)
- - [IpgeolocationSdk::Currency](docs/Currency.md)
- - [IpgeolocationSdk::ErrorResponse](docs/ErrorResponse.md)
- - [IpgeolocationSdk::GeolocationResponse](docs/GeolocationResponse.md)
- - [IpgeolocationSdk::BulkIPGeolocation](docs/BulkIPGeolocation.md)
- - [IpgeolocationSdk::BulkIPSecurity](docs/BulkIPSecurity.md)
- - [IpgeolocationSdk::Location](docs/Location.md)
- - [IpgeolocationSdk::LocationMinimal](docs/LocationMinimal.md)
- - [IpgeolocationSdk::Network](docs/Network.md)
- - [IpgeolocationSdk::NetworkAsn](docs/NetworkAsn.md)
- - [IpgeolocationSdk::NetworkCompany](docs/NetworkCompany.md)
- - [IpgeolocationSdk::NetworkMinimal](docs/NetworkMinimal.md)
- - [IpgeolocationSdk::NetworkMinimalAsn](docs/NetworkMinimalAsn.md)
- - [IpgeolocationSdk::NetworkMinimalCompany](docs/NetworkMinimalCompany.md)
- - [IpgeolocationSdk::ParseBulkUserAgentStringsRequest](docs/ParseBulkUserAgentStringsRequest.md)
- - [IpgeolocationSdk::Security](docs/Security.md)
- - [IpgeolocationSdk::SecurityAPIResponse](docs/SecurityAPIResponse.md)
- - [IpgeolocationSdk::TimeConversionResponse](docs/TimeConversionResponse.md)
- - [IpgeolocationSdk::TimeZone](docs/TimeZone.md)
- - [IpgeolocationSdk::TimeZoneDetailedResponse](docs/TimeZoneDetailedResponse.md)
- - [IpgeolocationSdk::TimeZoneDstEnd](docs/TimeZoneDstEnd.md)
- - [IpgeolocationSdk::TimeZoneDstStart](docs/TimeZoneDstStart.md)
- - [IpgeolocationSdk::TimezoneAirport](docs/TimezoneAirport.md)
- - [IpgeolocationSdk::TimezoneDetail](docs/TimezoneDetail.md)
- - [IpgeolocationSdk::TimezoneDetailDstEnd](docs/TimezoneDetailDstEnd.md)
- - [IpgeolocationSdk::TimezoneDetailDstStart](docs/TimezoneDetailDstStart.md)
- - [IpgeolocationSdk::TimezoneLocation](docs/TimezoneLocation.md)
- - [IpgeolocationSdk::TimezoneLocode](docs/TimezoneLocode.md)
- - [IpgeolocationSdk::UserAgentData](docs/UserAgentData.md)
- - [IpgeolocationSdk::UserAgentDataDevice](docs/UserAgentDataDevice.md)
- - [IpgeolocationSdk::UserAgentDataEngine](docs/UserAgentDataEngine.md)
- - [IpgeolocationSdk::UserAgentDataOperatingSystem](docs/UserAgentDataOperatingSystem.md)
+Example:
 
+```ruby
+begin
+  client.lookup_ip_geolocation(ip: "8.8.8.8")
+rescue IpgeolocationSdk::ApiError => error
+  puts error.status_code
+  puts error.api_message
+  puts error.message
+end
+```
+
+## Troubleshooting
+
+- `bulk lookup requires api_key in client config`
+  Bulk lookup does not support request-origin auth on its own.
+- `single lookup requires api_key or request_origin in client config`
+  Set at least one authentication option before calling the single lookup methods.
+- `XML output is not supported by typed methods`
+  Use `lookup_ip_geolocation_raw` or `bulk_lookup_ip_geolocation_raw` for XML output.
+- `client is closed`
+  Create a new client after calling `close`.
+- `TransportError` or `RequestTimeoutError`
+  Increase `connect_timeout` or `read_timeout`, or add your own retry logic.
+
+## Frequently Asked Questions
+
+<details>
+<summary><strong>Can I pass a plain hash instead of a request object?</strong></summary>
+Yes. All client methods accept either the typed request object or a plain hash with the same keys.
+</details>
+
+<details>
+<summary><strong>How do I look up my own public IP?</strong></summary>
+Call <code>lookup_ip_geolocation</code> with no <code>ip</code> value.
+</details>
+
+<details>
+<summary><strong>How do I get XML?</strong></summary>
+Use the raw methods with <code>output: IpgeolocationSdk::ResponseFormat::XML</code>.
+</details>
+
+<details>
+<summary><strong>How do I read bulk errors?</strong></summary>
+Check <code>result.success?</code>. Success items use <code>result.data</code>. Error items use <code>result.error.message</code>.
+</details>
+
+## Links
+
+- API docs: <https://ipgeolocation.io/documentation/ip-location-api.html>
+- Dashboard: <https://app.ipgeolocation.io/dashboard>
+- Pricing: <https://ipgeolocation.io/pricing.html>
+- RubyGems package: <https://rubygems.org/gems/ipgeolocation_sdk>
+- GitHub repo: <https://github.com/IPGeolocation/ip-geolocation-ruby-sdk>