openapi.yaml

openapi: 3.0.4
info:
  title: 'IPGeolocation.io'
  version: "3.0"
  description: |
    Combined OpenAPI specification for all IPGeolocation.io APIs.
    Includes IP Geolocation, IP Security, ASN Lookup, Abuse Contact,
    Astronomy, Timezone, and User Agent endpoints.
    
    ## API Overview
    
    This collection covers the following API groups:
    
    - **IP Geolocation**: Single and bulk IP/domain geolocation lookups
    - **IP Security**: VPN, proxy, Tor, bot, and threat intelligence
    - **ASN Lookup**: Autonomous System Number metadata and routing data
    - **IP Abuse Contact**: Registry-based abuse contact information
    - **Timezone**: Timezone lookup and time conversion
    - **User Agent**: Parse browser, device, and OS from User-Agent strings
    - **Astronomy**: Sunrise/sunset, moon phase, and astronomical data
    
    All endpoints are available at `https://api.ipgeolocation.io`. Every endpoint except `/v3/getip` requires authentication: an API key passed as the `apiKey` query parameter, or, for single lookups on paid plans, a registered Request Origin. Bulk endpoints always require an API key.
    
    Full documentation: https://ipgeolocation.io/documentation
    ## Billing & Credits

    Billing is based on API credits, not requests. Credits are charged only on successful HTTP 200 responses; the exact charge for a request is returned in the `X-Credits-Charged` response header.

    - **Free plan:** 1,000 credits per day (hard limit — no overage).
    - **Paid plans:** No rate limits. Each billing period includes a fixed credit allowance (Starter 150,000/month, Plus 500,000/month, Pro 1,000,000/month, Business 2,000,000/month, Premium 5,000,000/month). After the allowance is exhausted, requests keep succeeding only while overage (surcharge) is enabled and within its limit; otherwise the API returns HTTP 429.

    Credit cost per successful request: IP geolocation base lookup 1 credit (adding `security` +2, adding `abuse` +1, `include=*` → 4 credits); IP Security 2; Abuse Contact 1; ASN 1; Timezone 1; User-Agent 1; Astronomy 1.

    Each plan has a limit on the number of extra API keys and request origins:

    | Plan | Extra API Keys + Request Origins |
    |---|---|
    | Free | 0 |
    | Starter | 1 |
    | Plus | 2 |
    | Pro | 2 |
    | Business | 3 |
    | Premium | 3 |

    Additional keys or origins can be added for $2.50 per month each.

    Credits & usage: https://ipgeolocation.io/documentation/credits-usage.html
    Pricing: https://ipgeolocation.io/pricing.html

servers:
  - url: https://api.ipgeolocation.io
    description: IPGeolocation.io production server


tags:
  - name: IP Geolocation
    description: |
      IP geolocation API endpoints for looking up geographic location, network routing,
      ASN ownership, company attribution, timezone, currency, security threat intelligence,
      abuse contact, and User-Agent data. Accepts IPv4 addresses, IPv6 addresses, and
      domain names. The single lookup endpoint (`GET /v3/ipgeo`) resolves one IP or domain
      per request. The bulk lookup endpoint (`POST /v3/ipgeo-bulk`) accepts up to 50,000
      entries per request and requires a paid plan.
  - name: IP Security
    description: |
      IP security intelligence endpoints used to detect VPNs,
      proxies, Tor exit nodes, relay networks, bot activity,
      spam activity, cloud providers, and other anonymization
      technologies associated with IP addresses.

      The single lookup endpoint (`GET /v3/security`) analyzes
      one IP per request.

      The bulk lookup endpoint (`POST /v3/security-bulk`)
      accepts up to 50,000 IP addresses per request.
  - name: ASN Lookup
    description: |
      API endpoint for retrieving Autonomous System Number (ASN) information
      associated with IPv4 addresses, IPv6 addresses, or specific ASN numbers.

      The response includes ASN metadata such as the ASN number, organization
      name, country of registration, ASN type, domain, allocation details,
      routing statistics, and the Regional Internet Registry (RIR) responsible
      for the allocation.

      Additional routing intelligence such as peers, upstreams, downstreams,
      announced routes, and raw WHOIS registry data can also be retrieved
      using the `include` parameter.

      This information helps analyze internet routing, identify network
      operators, and understand how Autonomous Systems interconnect
      across the internet.
  - name: IP Abuse Contact
    description: |
      API endpoints for retrieving abuse contact information associated
      with IPv4 and IPv6 addresses. The response contains registry-based
      contact details for reporting malicious or abusive network activity
      such as spam, phishing, DDoS attacks, or unauthorized access attempts.

      The single lookup endpoint (`GET /v3/abuse`) returns one IP per
      request.

      The bulk lookup endpoint (`POST /v3/abuse-bulk`) accepts up to
      50,000 IP addresses per request.
  - name: Timezone
    description: |
      API endpoints for retrieving current date, time, and timezone
      information for a given input such as an IANA timezone identifier,
      geographic coordinates, location address, IPv4 or IPv6 address,
      airport codes (IATA or ICAO), or UN/LOCODE.

      The API can also convert timestamps between different timezones,
      locations, coordinates, airports, or UN/LOCODE identifiers.

      Responses include detailed timezone metadata such as UTC offset,
      daylight saving time (DST) status, formatted timestamps, and
      upcoming DST transition information. Depending on the lookup
      method used, the response may also include geolocation data,
      airport details, or city information.
  - name: User Agent
    description: |
      API endpoints for parsing user agent strings into browser, device, layout engine,
      and operating system details. Supports single lookups via request header, custom
      string lookups via JSON body, and bulk parsing of up to 50,000 strings per request.
      Also detects bots, crawlers, and malicious or malformed user agent strings.
  - name: Astronomy
    description: |
      API endpoints for retrieving astronomical information for a given
      location, including sunrise and sunset times, moonrise and moonset
      times, twilight phases, golden hour and blue hour windows, solar noon,
      sun and moon position data (altitude, azimuth, distance), and moon
      phase.

      A time series endpoint is also available to retrieve daily astronomical
      data across a date range of up to 90 days.




paths:
  /v3/ipgeo:
    get:
      operationId: lookupIpGeolocation
      security:
        - ApiKeyAuth: []
      summary: Single IP Geolocation Lookup
      description: |
        Returns geolocation and enrichment data for a single IPv4 address, IPv6 address,
        or domain name. When `ip` is omitted, the API resolves the caller's public IP
        automatically, which is useful for client-side lookups.

        The base response always includes `location`, `country_metadata`, `currency`,
        `asn`, and `time_zone`. Paid plans also get `network` and `company` by default.

        Use the `include` parameter to add optional modules such as `security`, `abuse`,
        `user_agent`, `geo_accuracy`, `dma_code`, and hostname resolution.

        Use `fields` and `excludes` to control exactly which parts of the response you
        receive. This reduces payload size and can improve response times.
      tags:
        - IP Geolocation
      parameters:
        - name: ip
          in: query
          required: false
          description: |
            An IPv4 address, IPv6 address, or domain name to look up. When omitted, the API
            resolves the public IP of the requesting client. Empty or whitespace-only values
            are treated the same as omission and resolve caller IP. Domain lookups require a
            paid plan. Pass `ip` only once. If multiple `ip` query parameters are sent,
            values may be merged and treated as invalid input (HTTP 400).
          schema:
            type: string
          example: "165.227.0.0"
        - name: lang
          in: query
          required: false
          description: |
            Language code for translated location names. Defaults to `en`. Supported values:
            `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`; any
            other value returns HTTP 400. Non-English values need a paid plan; on the Free
            plan they return HTTP 401. On `/v3/ipgeo-bulk` an unsupported value is returned for each
            entry as a `message` object inside the HTTP 200 array.

          schema:
            type: string
            default: "en"
            enum:
              - en
              - de
              - ru
              - ja
              - fr
              - cn
              - es
              - cs
              - it
              - ko
              - fa
              - pt
              - ar


        - name: include
          in: query
          required: false
          description: |
            Comma-separated list of optional data modules to add to the response. These are
            not returned by default. Requires a paid plan.

            If multiple hostname options are passed in `include`, hostname resolution uses
            this precedence order: `liveHostname` first, then `hostname`, then
            `hostnameFallbackLive`.
            If none is specified, the `hostname` field is not returned.

            For `user_agent`, the API parses the `User-Agent` header from the request. For
            server-side calls, forward your visitor's User-Agent string in the header so the
            parsed result matches the actual visitor.

            For additional query parameters (`include`, `fields`, `excludes`, `output`),
            unknown values are ignored. The API still returns HTTP 200 and applies only
            recognized values. Names are case-sensitive.

            `*` (or `all`, `any`) adds `geo_accuracy`, `dma_code`, `user_agent`, `security`,
            `abuse`, and `hostname` (local database). Live hostname lookups (`liveHostname`,
            `hostnameFallbackLive`) must be named separately.

            Free plan behavior: `include=*` (or `all`, `any`) is ignored and the default
            response is returned with HTTP 200. Any named module (`security`, `abuse`,
            `user_agent`, `geo_accuracy`, `dma_code`, `hostname`, `liveHostname`,
            `hostnameFallbackLive`) returns HTTP 401, even if the same module is also listed
            in `excludes`.
          schema:
            type: string
            example: "*"
        - name: fields
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to return. Fields and objects not listed
            are omitted, except add-ons requested with `include`: they are still returned when
            `fields` doesn't list them (e.g. `include=security&fields=location.city` returns
            `location.city` and `security`). To narrow an add-on, list a path inside it (e.g.
            `security.threat_score`). `dma_code` and `geo_accuracy` likewise add their own
            `location` fields.
            The `ip` field, and `domain` on domain lookups, are always returned; `fields` and
            `excludes` cannot remove them.

            Supports dot-notation for nested fields: `location.city`, `asn.organization`.
            To return an entire object, use the object key: `location`, `security`.

            If a field belongs to an optional module (e.g. `security.threat_score`), you
            must also pass the corresponding `include` value.
            If you omit `include`, the request still succeeds, but fields from optional
            modules are not returned.
            A path into an object that is empty for this IP (for example
            `time_zone.dst_start.utc_time` for a zone without DST) is still valid; the object
            comes back empty (`{}`).

            If the same field or object is listed in both `fields` and `excludes`,
            `excludes` wins and it is left out of the response. An object left with no
            fields after `excludes` is removed.
            `excludes` also wins over `include`: an add-on that is excluded is not looked up
            or returned, and its extra credits are not charged. This covers `security`,
            `abuse`, `user_agent`, `hostname` (for all three hostname options), `dma_code` and
            `geo_accuracy`: `excludes=dma_code` removes `location.dma_code`,
            `excludes=geo_accuracy` removes `location.locality`, `location.accuracy_radius`
            and `location.confidence`, and `excludes=location` removes both.
            `object.*` removes the whole object; `*` is recognized only as the last part of a
            path (`location.*.city` is ignored).

            If you list both an object key and one of its nested fields separated by comma
            (e.g. `security,security.threat_score`), the full object is returned.

            Unknown names are ignored and the API still returns HTTP 200. Names are
            case-sensitive. If none of the names in `fields` is valid, `fields` is ignored
            and the full response is returned (and charged). `*` anywhere in `fields`
            returns everything.

            Available on all plans including Free.
          schema:
            type: string
            example: "location.city,asn.organization"

        - name: excludes
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to remove from the response. The `ip`
            field, and `domain` on domain lookups, are always returned; `fields` and
            `excludes` cannot remove them.

            Supports dot-notation for nested fields: `location.continent_code`.
            To exclude an entire object, use the object key: `currency`, `time_zone`.

            If the same field or object is listed in both `fields` and `excludes`,
            `excludes` wins and it is left out of the response. An object left with no
            fields after `excludes` is removed.
            `excludes` also wins over `include`: an add-on that is excluded is not looked up
            or returned, and its extra credits are not charged. This covers `security`,
            `abuse`, `user_agent`, `hostname` (for all three hostname options), `dma_code` and
            `geo_accuracy`: `excludes=dma_code` removes `location.dma_code`,
            `excludes=geo_accuracy` removes `location.locality`, `location.accuracy_radius`
            and `location.confidence`, and `excludes=location` removes both.
            `object.*` removes the whole object; `*` is recognized only as the last part of a
            path (`location.*.city` is ignored).

            Unknown fields or object keys in `excludes` are ignored. The API still returns
            HTTP 200.

            Available on all plans including Free.
          schema:
            type: string
            example: "location.continent_code,currency,company.type"
        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200.
          schema:
            type: string
            enum: [json, xml]
            default: json

      responses:
        "200":
          description: Geolocation data for the requested IP or domain.
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IpGeolocationResponse"
              examples:
                paidFullResponse:
                  summary: Paid plan, all modules included
                  value:
                    ip: "91.128.103.196"
                    hostname: "91.128.103.196"
                    location:
                      continent_code: "EU"
                      continent_name: "Europe"
                      country_code2: "SE"
                      country_code3: "SWE"
                      country_name: "Sweden"
                      country_name_official: "Kingdom of Sweden"
                      country_capital: "Stockholm"
                      state_prov: "Stockholms län"
                      state_code: "SE-AB"
                      district: "Stockholm"
                      city: "Stockholm"
                      locality: "Stockholm"
                      accuracy_radius: "4.395"
                      confidence: "high"
                      dma_code: ""
                      zipcode: "164 40"
                      latitude: "59.40510"
                      longitude: "17.95510"
                      is_eu: true
                      country_flag: "https://ipgeolocation.io/static/flags/se_64.png"
                      geoname_id: "9972319"
                      country_emoji: "\U0001F1F8\U0001F1EA"
                    country_metadata:
                      calling_code: "+46"
                      tld: ".se"
                      languages:
                        - "sv-SE"
                        - "se"
                        - "sma"
                        - "fi-SE"
                    network:
                      connection_type: ""
                      route: "91.128.0.0/14"
                      is_anycast: false
                      is_cdn: false
                      cdn_provider_name: ""
                    currency:
                      code: "SEK"
                      name: "Swedish Krona"
                      symbol: "kr"
                    asn:
                      as_number: "AS1257"
                      organization: "Tele2 Sverige AB"
                      country: "SE"
                      type: "ISP"
                      domain: "tele2.com"
                      date_allocated: "2024-12-13"
                      rir: "RIPE"
                    company:
                      name: "Tele2 Sverige AB"
                      type: "ISP"
                      domain: "tele2.com"
                    security:
                      threat_score: 0
                      is_tor: false
                      is_proxy: false
                      proxy_provider_names: []
                      proxy_confidence_score: 0
                      proxy_last_seen: ""
                      proxy_days_seen_30d: 0
                      proxy_days_seen_7d: 0
                      proxy_provider_count_30d: 0
                      is_residential_proxy: false
                      is_vpn: false
                      vpn_provider_names: []
                      vpn_confidence_score: 0
                      vpn_last_seen: ""
                      is_relay: false
                      relay_provider_name: ""
                      is_anonymous: false
                      is_known_attacker: false
                      is_bot: false
                      bot_confidence_score: 0
                      bot_operator_name: ""
                      bot_type: ""
                      is_known_good_bot: false
                      bot_last_seen: ""
                      is_spam: false
                      is_cloud_provider: false
                      cloud_provider_name: ""
                      is_corporate_gateway: false
                      corporate_gateway_type: ""
                      corporate_gateway_provider_name: ""
                    abuse:
                      route: "91.128.0.0/14"
                      country: "SE"
                      name: "Swipnet Staff"
                      organization: ""
                      kind: "group"
                      address: "Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN"
                      emails:
                        - "abuse@tele2.com"
                      phone_numbers:
                        - "+46 8 5626 42 10"
                    time_zone:
                      name: "Europe/Stockholm"
                      offset: 1
                      offset_with_dst: 1
                      current_time: "2026-02-13 09:19:24.410+0100"
                      current_time_unix: 1770970764.41
                      current_tz_abbreviation: "CET"
                      current_tz_full_name: "Central European Standard Time"
                      standard_tz_abbreviation: "CET"
                      standard_tz_full_name: "Central European Standard Time"
                      is_dst: false
                      dst_savings: 0
                      dst_exists: true
                      dst_tz_abbreviation: "CEST"
                      dst_tz_full_name: "Central European Summer Time"
                      dst_start:
                        utc_time: "2026-03-29 TIME 01:00"
                        duration: "+1.00H"
                        gap: true
                        date_time_after: "2026-03-29 TIME 03:00"
                        date_time_before: "2026-03-29 TIME 02:00"
                        overlap: false
                      dst_end:
                        utc_time: "2026-10-25 TIME 01:00"
                        duration: "-1.00H"
                        gap: false
                        date_time_after: "2026-10-25 TIME 02:00"
                        date_time_before: "2026-10-25 TIME 03:00"
                        overlap: true
                    user_agent:
                      user_agent_string: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0"
                      name: "Edge"
                      type: "Browser"
                      version: "143"
                      version_major: "143"
                      device:
                        name: "Linux Desktop"
                        type: "Desktop"
                        brand: "Unknown"
                        cpu: "Intel x86_64"
                      engine:
                        name: "Blink"
                        type: "Browser"
                        version: "143"
                        version_major: "143"
                      operating_system:
                        name: "Linux"
                        type: "Desktop"
                        version: "??"
                        version_major: "??"
                        build: "??"
                freeMinimalResponse:
                  summary: Free plan default response
                  value:
                    ip: "165.227.0.0"
                    location:
                      continent_code: "NA"
                      continent_name: "North America"
                      country_code2: "US"
                      country_code3: "USA"
                      country_name: "United States"
                      country_name_official: "United States of America"
                      country_capital: "Washington, D.C."
                      state_prov: "California"
                      state_code: "US-CA"
                      district: "Santa Clara County"
                      city: "Santa Clara"
                      zipcode: "95051"
                      latitude: "37.35983"
                      longitude: "-121.98144"
                      is_eu: false
                      country_flag: "https://ipgeolocation.io/static/flags/us_64.png"
                      geoname_id: "5346804"
                      country_emoji: "\U0001F1FA\U0001F1F8"
                    country_metadata:
                      calling_code: "+1"
                      tld: ".us"
                      languages:
                        - "en-US"
                        - "es-US"
                        - "haw"
                        - "fr"
                    currency:
                      code: "USD"
                      name: "US Dollar"
                      symbol: "$"
                    asn:
                      as_number: "AS14061"
                      organization: "DigitalOcean, LLC"
                      country: "US"
                    time_zone:
                      name: "America/Los_Angeles"
                      offset: -8
                      offset_with_dst: -8
                      current_time: "2026-02-09 09:54:51.206-0800"
                      current_time_unix: 1770659691.206
                      current_tz_abbreviation: "PST"
                      current_tz_full_name: "Pacific Standard Time"
                      standard_tz_abbreviation: "PST"
                      standard_tz_full_name: "Pacific Standard Time"
                      is_dst: false
                      dst_savings: 0
                      dst_exists: true
                      dst_tz_abbreviation: "PDT"
                      dst_tz_full_name: "Pacific Daylight Time"
                      dst_start:
                        utc_time: "2026-03-08 TIME 10:00"
                        duration: "+1.00H"
                        gap: true
                        date_time_after: "2026-03-08 TIME 03:00"
                        date_time_before: "2026-03-08 TIME 02:00"
                        overlap: false
                      dst_end:
                        utc_time: "2026-11-01 TIME 09:00"
                        duration: "-1.00H"
                        gap: false
                        date_time_after: "2026-11-01 TIME 01:00"
                        date_time_before: "2026-11-01 TIME 02:00"
                        overlap: true
        "400":
          description: |
            Bad request. Returned for one of the following reasons:

            - The provided IPv4 address, IPv6 address, or domain name is invalid.
            - Special characters such as [ ] { } | ^ ` are present in the API URL,
              either in a parameter name or its value (especially in the API key).
            - An invalid or unsupported `lang` parameter is provided.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidIp:
                  summary: Invalid IPv4/IPv6/domain input
                  value:
                    message: "Provided name, service or IP address '999.999.999.999' is not valid."
                specialCharacters:
                  summary: Special characters in API URL or key
                  value:
                    message: "Invalid character found in the request target."
                invalidLang:
                  summary: Unsupported lang parameter value
                  value:
                    message: "This 'zz' lang is not valid. Please use 'en' as the default language"
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:

            - An API key is required for this request, but the `apiKey` query parameter is
              missing and the request doesn't come from a domain added under Request Origin.
            - An invalid (random or incorrect) API key is provided, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - The API request is made using an API key for a database subscription.
            - The subscription is in a 'paused' state.
            - The subscription trial has expired.
            - Any of the following `include` values are used with a Free/Developer plan API key:
              `hostname`, `liveHostname`, `hostnameFallbackLive`, `security`,
              `abuse`, `geo_accuracy`, `dma_code`, or `user_agent`.
            - A domain name lookup is performed using a Free subscription API key.
            - A language other than English is specified in the `lang` parameter
              while using a Free/Developer plan API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscriptionKey:
                  summary: Database subscription API key used for REST API
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
                freePlanInclude:
                  summary: Free plan used with include=security
                  value:
                    message: "IP-security lookup is not supported on your subscription. This feature is available on Paid subscriptions only."
                freePlanDomain:
                  summary: Free plan used with domain lookup
                  value:
                    message: "IP to geolocation lookup for domain or service name is not supported on your current subscription. This feature is available to all paid subscriptions only."
                freePlanLang:
                  summary: Free plan used with non-English lang value
                  value:
                    message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: |
            Not found. Returned for one of the following reasons:

            - A syntactically valid IPv4 or IPv6 address, or the IP a domain resolves to,
              does not exist in the IPGeolocation database (for a domain: "Provided domain
              or service name 'example.com' doesn't exist in our database.").
            - An IPv4 address, IPv6 address, or domain name is passed as a path variable
              instead of as a URL query parameter (e.g., using `/v3/ipgeo/8.8.8.8`
              instead of `/v3/ipgeo?ip=8.8.8.8`).
            - A non-existent or incorrect API endpoint is called.

            Invalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ipNotInDatabase:
                  summary: IPv4/IPv6 not found in database
                  value:
                    message: "Provided IP Address 'IP_ADDRESS' doesn't exist in our database."
                ipAsPathVariable:
                  summary: IP passed as path variable instead of query parameter
                  value:
                    message: "No endpoint GET /v3/ipgeo/8.8.8.8."
                wrongEndpoint:
                  summary: Incorrect or non-existent endpoint
                  value:
                    message: "No endpoint GET /v3/security-invalid."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "423":
          $ref: "#/components/responses/Locked"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

  /v3/ipgeo-bulk:
    post:
      operationId: bulkLookupIpGeolocation
      security:
        - ApiKeyAuth: []
      summary: Bulk IP Geolocation Lookup
      description: |
        Returns geolocation and enrichment data for up to 50,000 IPv4 addresses, IPv6
        addresses, or domain names in a single request. The request body must be a JSON
        object with an `ips` array.

        This endpoint requires a paid plan.

        The response is a JSON array with one element per IP in the request. Each element
        is either a lookup result or an object with only a `message` field. An entry gets
        a `message` object when it is invalid, empty or `null`, not in the database, a
        bogon or private IP, or when `lang` is unsupported. These entries are not charged.

        This endpoint supports the same query parameters as the single lookup endpoint,
        including `lang`, `include`, `fields`, `excludes`, and `output`.

        Credits are calculated as: credits per lookup multiplied by the number of valid
        IPs in the request. The total is returned in the `X-Credits-Charged` response
        header. When at least one submitted ip is invalid, the `X-Successful-Record`
        response header indicates how many entries were successfully resolved.

        Only the `POST` method is accepted. Sending a `GET` request returns HTTP 405.
      tags:
        - IP Geolocation
      parameters:
        - name: lang
          in: query
          required: false
          description: |
            Language code for translated location names. Defaults to `en`. Supported values:
            `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`. On
            `/v3/ipgeo-bulk`, an unsupported value does not fail the request: each entry is
            returned as a `message` object inside the HTTP 200 array.
          schema:
            type: string
            default: "en"
            enum:
              - en
              - de
              - ru
              - ja
              - fr
              - cn
              - es
              - cs
              - it
              - ko
              - fa
              - pt
              - ar


        - name: include
          in: query
          required: false
          description: |
            Comma-separated list of optional data modules to add to the response. These are
            not returned by default. Requires a paid plan.

            If multiple hostname options are passed in `include`, hostname resolution uses
            this precedence order: `liveHostname` first, then `hostname`, then
            `hostnameFallbackLive`.
            If none is specified, the `hostname` field is not returned.

            For `user_agent`, the API parses the `User-Agent` header from the request. For
            server-side calls, forward your visitor's User-Agent string in the header so the
            parsed result matches the actual visitor.

            For additional query parameters (`include`, `fields`, `excludes`, `output`),
            unknown values are ignored. The API still returns HTTP 200 and applies only
            recognized values. Names are case-sensitive.

            `*` (or `all`, `any`) adds `geo_accuracy`, `dma_code`, `user_agent`, `security`,
            `abuse`, and `hostname` (local database). Live hostname lookups (`liveHostname`,
            `hostnameFallbackLive`) must be named separately.
          schema:
            type: string
            example: "*"
        - name: fields
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to return. Fields and objects not listed
            are omitted, except add-ons requested with `include`: they are still returned when
            `fields` doesn't list them (e.g. `include=security&fields=location.city` returns
            `location.city` and `security`). To narrow an add-on, list a path inside it (e.g.
            `security.threat_score`). `dma_code` and `geo_accuracy` likewise add their own
            `location` fields.
            The `ip` field, and `domain` on domain lookups, are always returned; `fields` and
            `excludes` cannot remove them.

            Supports dot-notation for nested fields: `location.city`, `asn.organization`.
            To return an entire object, use the object key: `location`, `security`.

            If a field belongs to an optional module (e.g. `security.threat_score`), you
            must also pass the corresponding `include` value.
            If you omit `include`, the request still succeeds, but fields from optional
            modules are not returned.
            A path into an object that is empty for this IP (for example
            `time_zone.dst_start.utc_time` for a zone without DST) is still valid; the object
            comes back empty (`{}`).

            If the same field or object is listed in both `fields` and `excludes`,
            `excludes` wins and it is left out of the response. An object left with no
            fields after `excludes` is removed.
            `excludes` also wins over `include`: an add-on that is excluded is not looked up
            or returned, and its extra credits are not charged. This covers `security`,
            `abuse`, `user_agent`, `hostname` (for all three hostname options), `dma_code` and
            `geo_accuracy`: `excludes=dma_code` removes `location.dma_code`,
            `excludes=geo_accuracy` removes `location.locality`, `location.accuracy_radius`
            and `location.confidence`, and `excludes=location` removes both.
            `object.*` removes the whole object; `*` is recognized only as the last part of a
            path (`location.*.city` is ignored).

            If you list both an object key and one of its nested fields separated by comma
            (e.g. `security,security.threat_score`), the full object is returned.

            Unknown names are ignored and the API still returns HTTP 200. Names are
            case-sensitive. If none of the names in `fields` is valid, `fields` is ignored
            and the full response is returned (and charged). `*` anywhere in `fields`
            returns everything.
          schema:
            type: string
            example: "location.city,asn.organization"

        - name: excludes
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to remove from the response. The `ip`
            field, and `domain` on domain lookups, are always returned; `fields` and
            `excludes` cannot remove them.

            Supports dot-notation for nested fields: `location.continent_code`.
            To exclude an entire object, use the object key: `currency`, `time_zone`.

            If the same field or object is listed in both `fields` and `excludes`,
            `excludes` wins and it is left out of the response. An object left with no
            fields after `excludes` is removed.
            `excludes` also wins over `include`: an add-on that is excluded is not looked up
            or returned, and its extra credits are not charged. This covers `security`,
            `abuse`, `user_agent`, `hostname` (for all three hostname options), `dma_code` and
            `geo_accuracy`: `excludes=dma_code` removes `location.dma_code`,
            `excludes=geo_accuracy` removes `location.locality`, `location.accuracy_radius`
            and `location.confidence`, and `excludes=location` removes both.
            `object.*` removes the whole object; `*` is recognized only as the last part of a
            path (`location.*.city` is ignored).

            Unknown fields or object keys in `excludes` are ignored. The API still returns
            HTTP 200.
          schema:
            type: string
            example: "location.continent_code,currency,company.type"
        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200.
          schema:
            type: string
            enum: [json, xml]
            default: json

      requestBody:
        required: true
        description: |
          A JSON object containing an `ips` array. Each element is a string representing
          an IPv4 address, IPv6 address, or domain name. The array must not be empty and
          must not contain more than 50,000 entries.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkGeolocationRequest"
            examples:
              mixedIps:
                summary: Mixed IPv4, IPv6, and domain
                value:
                  ips:
                    - "8.8.8.8"
                    - "91.128.103.196"
                    - "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
                    - "ipgeolocation.io"
              ipv4Only:
                summary: Multiple IPv4 addresses
                value:
                  ips:
                    - "8.8.8.8"
                    - "8.8.4.4"
                    - "165.227.0.0"
      responses:
        "200":
          description: |
            An array of results, one per input entry. Each element is either a lookup
            result or an object with only a `message` field. An entry gets a `message`
            object when it is invalid, empty or `null`, not in the database, a bogon or
            private IP, or when `lang` is unsupported. These entries are not charged.
            `X-Successful-Record` is returned only when at least one submitted entry
            fails and the number of successful lookups is lower than the number of
            submitted entries.
          headers:
            X-Credits-Charged:
              description: |
                Total number of API credits consumed. Equals credits per lookup
                multiplied by the count of valid IPs.
              schema:
                type: number
                example: 1
            X-Successful-Record:
              description: |
                Number of valid IP addresses or domains that were successfully resolved in
                this bulk request. Invalid, bogon, and private IPs are not counted.
                This header is included only when at least one bulk entry returns an
                error message and total successful lookups are fewer than submitted
                entries.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BulkGeolocationResponseItem"
              examples:
                bulkResponse:
                  summary: Bulk response with one valid and one error entry
                  value:
                    - ip: "8.8.8.8"
                      location:
                        continent_code: "NA"
                        continent_name: "North America"
                        country_code2: "US"
                        country_code3: "USA"
                        country_name: "United States"
                        country_name_official: "United States of America"
                        country_capital: "Washington, D.C."
                        state_prov: "California"
                        state_code: "US-CA"
                        district: "Santa Clara County"
                        city: "Mountain View"
                        zipcode: "94043"
                        latitude: "37.42240"
                        longitude: "-122.08421"
                        is_eu: false
                        country_flag: "https://ipgeolocation.io/static/flags/us_64.png"
                        geoname_id: "5375480"
                        country_emoji: "\U0001F1FA\U0001F1F8"
                      country_metadata:
                        calling_code: "+1"
                        tld: ".us"
                        languages:
                          - "en-US"
                          - "es-US"
                          - "haw"
                          - "fr"
                      network:
                        connection_type: ""
                        route: "8.8.8.0/24"
                        is_anycast: true
                        is_cdn: false
                        cdn_provider_name: ""
                      currency:
                        code: "USD"
                        name: "US Dollar"
                        symbol: "$"
                      asn:
                        as_number: "AS15169"
                        organization: "Google LLC"
                        country: "US"
                        type: "BUSINESS"
                        domain: "google.com"
                        date_allocated: "2000-03-30"
                        rir: "ARIN"
                      company:
                        name: "Google LLC"
                        type: "HOSTING"
                        domain: "google.com"
                      time_zone:
                        name: "America/Los_Angeles"
                        offset: -8
                        offset_with_dst: -8
                        current_time: "2026-02-09 09:54:51.206-0800"
                        current_time_unix: 1770659691.206
                        current_tz_abbreviation: "PST"
                        current_tz_full_name: "Pacific Standard Time"
                        standard_tz_abbreviation: "PST"
                        standard_tz_full_name: "Pacific Standard Time"
                        is_dst: false
                        dst_savings: 0
                        dst_exists: true
                        dst_tz_abbreviation: "PDT"
                        dst_tz_full_name: "Pacific Daylight Time"
                        dst_start:
                          utc_time: "2026-03-08 TIME 10:00"
                          duration: "+1.00H"
                          gap: true
                          date_time_after: "2026-03-08 TIME 03:00"
                          date_time_before: "2026-03-08 TIME 02:00"
                          overlap: false
                        dst_end:
                          utc_time: "2026-11-01 TIME 09:00"
                          duration: "-1.00H"
                          gap: false
                          date_time_after: "2026-11-01 TIME 01:00"
                          date_time_before: "2026-11-01 TIME 02:00"
                          overlap: true
                    - message: "'10.0.0.1' is a bogon IP address."
        "400":
          description: |
            Bad request. Returned for the whole request only when the body is missing or not
            valid JSON, `ips` is missing, is not a JSON array, or is empty, or `ips` has more
            than 50,000 entries, or when special characters such as [ ] { } | ^ ` are
            present in the API URL, either in a parameter name or its value (especially in
            the API key). An invalid IP or domain or an unsupported `lang` does not fail the
            request: that entry is returned as a `message` object inside the HTTP 200 array.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                specialCharacters:
                  summary: Special characters in API URL or key
                  value:
                    message: "Invalid character found in the request target."
                malformedJson:
                  summary: Malformed JSON body for bulk endpoint
                  value:
                    message: "Malformed JSON request or invalid field"
                missingIps:
                  summary: Bulk body missing ips field
                  value:
                    message: "IP addresses for bulk lookup are missing"
                ipsNotArray:
                  summary: Bulk ips field is not a JSON array
                  value:
                    message: "'ips' must be a JSON array of strings, e.g. {\"ips\": [\"value1\", \"value2\"]}"
                emptyBulkIps:
                  summary: Bulk ips array is empty
                  value:
                    message: "'ips' must not be empty or null"
                tooManyBulkEntries:
                  summary: Bulk body exceeds 50,000 entries
                  value:
                    message: "No. of lookup queries cannot be more than 50000"
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:

            - The `apiKey` URL parameter is missing.
            - An invalid (random or incorrect) API key is provided.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - The API request is made using an API key for a database subscription.
            - The subscription is in a 'paused' state.
            - The subscription trial has expired.
            - The bulk IP geolocation endpoint is called using Request Origin (CORS)
              authentication. Bulk requests require an `apiKey` and cannot be authenticated
              using Request Origin alone.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscriptionKey:
                  summary: Database subscription API key used for REST API
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
                requestOriginBulk:
                  summary: Bulk endpoint called using Request Origin authentication
                  value:
                    message: "Bulk queries are not allowed with request origins. Please use an API key to perform bulk queries."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "405":
          $ref: "#/components/responses/MethodNotAllowedBulk"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "415":
          $ref: "#/components/responses/UnsupportedMediaType"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"


  /v3/getip:
    get:
      operationId: getCallerIp
      summary: Get caller's public IP address
      description: |
        Returns the public IP address of the client that calls this endpoint. If
        called from a server, this returns the server's IP. If called from a browser
        via client-side JavaScript, this returns the visitor's public IP address.

        This endpoint does not require authentication. It can be called without an
        `apiKey` query parameter and without an IPGeolocation.io account.

        Use this endpoint when you only need the caller's public IP address. For
        full geolocation, network, ASN, and other enrichment data, use
        `GET /v3/ipgeo` instead.
      tags:
        - IP Geolocation
      security: []
      parameters:
        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified.

            If `output` is unknown or unsupported, it is ignored and the response
            defaults to JSON (`application/json`) with HTTP 200.
          schema:
            type: string
            enum:
              - "json"
              - "xml"
              - "text"
            default: "json"
          examples:
            json:
              summary: JSON response (default)
              value: "json"
            xml:
              summary: XML response
              value: "xml"
            text:
              summary: Plain text response
              value: "text"
      responses:
        "200":
          description: The caller's public IP address.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetIpResponse"
              example:
                ip: "8.8.8.8"
            application/xml:
              schema:
                $ref: "#/components/schemas/GetIpResponse"
              example: |
                <LinkedHashMap>
                  <ip>8.8.8.8</ip>
                </LinkedHashMap>
            text/plain:
              schema:
                type: string
                description: |
                  The caller's public IP address as a raw string, with no surrounding
                  JSON or XML.
                example: "8.8.8.8"
              example: "8.8.8.8"
        "404":
          description: |
            Not found. Returned when a path segment is added after `/v3/getip` (for
            example `/v3/getip/8.8.8.8`). This endpoint takes no path variables.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: "No endpoint GET /v3/getip/8.8.8.8."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"


  /v3/security:
    get:
      operationId: lookupIpSecurity
      security:
        - ApiKeyAuth: []
      summary: Single IP Security Lookup
      description: |
        Returns threat intelligence and anonymization signals for a single
        IPv4 or IPv6 address.

        If the `ip` parameter is omitted, the API automatically detects the
        caller's public IP address and returns its security risk signals.

        The response includes a threat score and multiple indicators such
        as VPN usage, proxy usage, Tor exit node detection, relay networks,
        bot activity, spam activity, and cloud hosting infrastructure.

        When available, provider names, confidence scores, and last-seen
        timestamps are included.

        Use the `fields` and `excludes` parameters to control which parts
        of the response are returned.
      tags:
        - IP Security
      parameters:
        - name: ip
          in: query
          required: false
          description: |
            An IPv4 address or IPv6 address to look up. When omitted, the API
            resolves the public IP of the requesting client. Empty or whitespace-only values
            are treated the same as omission and resolve caller IP. Pass `ip` only once. If multiple `ip` query parameters are sent,
            values may be merged and treated as invalid input (HTTP 400).
          schema:
            type: string
            example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"

        - name: fields
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to return. Everything else is omitted.
            The `ip` field is always returned regardless of this filter.

            Supports dot-notation for nested fields: `security.is_tor`, `security.threat_score`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins and it
            is left out of the response (e.g. `fields=security.is_vpn&excludes=security.is_vpn` drops
            `is_vpn`). An object left with no fields is removed, so `fields=security&excludes=security`
            returns only `ip`.

            If you list both an object key and one of its nested fields separated by comma
            (e.g. `security,security.is_vpn`), the full object is returned.

            Unknown names are ignored and the API still returns HTTP 200; if no name in
            `fields` is a real field, the full response is returned.

            This parameter only has an effect once a request is authorized; the IP Security
            API as a whole requires a paid plan.
          schema:
            type: string
            example: "security.is_tor,security.is_vpn"

        - name: excludes
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to remove from the response. The `ip`
            field cannot be excluded.

            Supports dot-notation for nested fields: `security.is_relay`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins and it
            is left out of the response (e.g. `fields=security.is_vpn&excludes=security.is_vpn` drops
            `is_vpn`). An object left with no fields is removed, so `fields=security&excludes=security`
            returns only `ip`.

            Unknown fields or object keys in `excludes` are ignored. The API still returns
            HTTP 200.

            This parameter only has an effect once a request is authorized; the IP Security
            API as a whole requires a paid plan.
          schema:
            type: string
            example: "security.proxy_provider_names,security.is_residential_proxy"

        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json
      responses:
        "200":
          description: |
            Security intelligence for the requested IP.

            If the IP is not in the security database, the response is still 200 with every
            flag false, scores and counts 0, and empty names, lists and dates.
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 2
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IpSecurityResponse"
              example:
                ip: "2.56.188.34"
                security:
                  threat_score: 80
                  is_tor: false
                  is_proxy: true
                  proxy_provider_names: [
                    "Zyte Proxy"
                  ]
                  proxy_confidence_score: 80
                  proxy_last_seen: "2025-12-12"
                  proxy_days_seen_30d: 4
                  proxy_days_seen_7d: 1
                  proxy_provider_count_30d: 1
                  is_residential_proxy: true
                  is_vpn: true
                  vpn_provider_names: [
                    "Nord VPN"
                  ]
                  vpn_confidence_score: 80
                  vpn_last_seen: "2026-01-19"
                  is_relay: false
                  relay_provider_name: ""
                  is_anonymous: true
                  is_known_attacker: true
                  is_bot: false
                  bot_confidence_score: 0
                  bot_operator_name: ""
                  bot_type: ""
                  is_known_good_bot: false
                  bot_last_seen: ""
                  is_spam: false
                  is_cloud_provider: true
                  cloud_provider_name: "Packethub S.A."
                  is_corporate_gateway: false
                  corporate_gateway_type: ""
                  corporate_gateway_provider_name: ""
        "400":
          description: |
            Bad request. Returned for one of the following reasons:

            - The provided IPv4 or IPv6 address is invalid. This API does not accept domain
              names in the `ip` parameter — a domain name is rejected the same way as any
              other non-IP string.
            - Special characters such as [ ] { } | ^ ` are present in the API URL,
              either in a parameter name or its value (especially in the API key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidIp:
                  summary: Invalid IPv4/IPv6 input
                  value:
                    message: "Provided IP address '999.999.999.999' is not valid."
                specialCharacters:
                  summary: Special characters in API URL or key
                  value:
                    message: "Invalid character found in the request target."
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:

            - An API key is required for this request, but the `apiKey` query parameter is missing and the request doesn't come from a domain added under Request Origin.
            - An invalid (random or incorrect) API key is provided, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - The API request is made using an API key for a database subscription.
            - The API request is made using a free subscription API key.
            - The subscription is in a 'paused' state.
            - The subscription trial has expired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"

                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"

                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"

                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"

                databaseSubscriptionKey:
                  summary: Database subscription API key used for REST API
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."

                freePlanAccess:
                  summary: Free subscription used for single IP Security lookup
                  value:
                    message: "IP Security Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."

                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."

                trialExpired:
                  summary: Subscription trial has expired
                  value:
                    message: "Your subscription trial has been expired. Please subscribe to a paid plan to use IPGeolocation API."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: |
            Not found. Returned for one of the following reasons:

            - An IPv4 address, IPv6 address, or domain name is passed as a path variable
              instead of as a URL query parameter (e.g., using `/v3/security/8.8.8.8`
              instead of `/v3/security?ip=8.8.8.8`).
            - A non-existent or incorrect API endpoint is called.

            An IP address that is not in the security database does not return 404; it
            returns HTTP 200 with the default security object. Invalid or malformed IPv4,
            IPv6, or domain input returns HTTP 400 instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ipAsPathVariable:
                  summary: IP passed as path variable instead of query parameter
                  value:
                    message: "No endpoint GET /v3/security/8.8.8.8."
                wrongEndpoint:
                  summary: Incorrect or non-existent endpoint
                  value:
                    message: "No endpoint GET /v3/security-invalid."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "423":
          $ref: "#/components/responses/Locked"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

  /v3/security-bulk:
    post:
      operationId: bulkLookupIpSecurity
      security:
        - ApiKeyAuth: []
      summary: Bulk IP Security Lookup
      description: |
        Returns security intelligence for up to **50,000 IPv4 or IPv6
        addresses** in a single request.

        The request body must contain an `ips` array.

        Each IP is processed independently, and surrounding spaces are trimmed. Invalid,
        empty, null, bogon, or private entries return an object containing only a
        `message` field; the rest of the request still succeeds.

        Credits are charged **per valid IP address** using the same
        pricing rules as the single lookup endpoint.

        When at least one entry is invalid, the response header
        `X-Successful-Record` indicates the number of successful
        lookups.

        Only the `POST` method is supported for this endpoint.
      tags:
        - IP Security
      parameters:
        - name: fields
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to return. Everything else is omitted.
            The `ip` field is always returned regardless of this filter.

            Supports dot-notation for nested fields: `security.is_tor`, `security.threat_score`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins and it
            is left out of the response (e.g. `fields=security.is_vpn&excludes=security.is_vpn` drops
            `is_vpn`). An object left with no fields is removed, so `fields=security&excludes=security`
            returns only `ip`.

            If you list both an object key and one of its nested fields separated by comma
            (e.g. `security,security.is_vpn`), the full object is returned.

            Unknown names are ignored and the API still returns HTTP 200; if no name in
            `fields` is a real field, the full response is returned.

            This parameter only has an effect once a request is authorized; the IP Security
            API as a whole requires a paid plan.
          schema:
            type: string
            example: "security.is_tor,security.is_vpn"

        - name: excludes
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to remove from the response. The `ip`
            field cannot be excluded.

            Supports dot-notation for nested fields: `security.is_relay`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins and it
            is left out of the response (e.g. `fields=security.is_vpn&excludes=security.is_vpn` drops
            `is_vpn`). An object left with no fields is removed, so `fields=security&excludes=security`
            returns only `ip`.

            Unknown fields or object keys in `excludes` are ignored. The API still returns
            HTTP 200.

            This parameter only has an effect once a request is authorized; the IP Security
            API as a whole requires a paid plan.
          schema:
            type: string
            example: "security.proxy_provider_names,security.is_residential_proxy"

        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json
      requestBody:
        required: true
        description: |
          A JSON object containing an `ips` array. Each element is a string representing
          an IPv4 address or IPv6 address. The array must not be empty and
          must not contain more than 50,000 entries.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkSecurityRequest"
            examples:
              mixedIps:
                summary: Mixed IPv4 and IPv6
                value:
                  ips:
                    - "8.8.8.8"
                    - "91.128.103.196"
                    - "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
              ipv4Only:
                summary: Multiple IPv4 addresses
                value:
                  ips:
                    - "8.8.8.8"
                    - "8.8.4.4"
                    - "165.227.0.0"
      responses:
        "200":
          description: |
            An array of results, one per input IP address.

            Valid entries return a security lookup object containing the IP address
            and its associated security intelligence.

            Invalid, empty, null, private, or bogon entries return an object containing
            only a `message` field; the rest of the request still succeeds.

            The `X-Successful-Record` response header is returned only when the request
            contains one or more invalid entries and indicates the number of successful
            lookups.
          headers:
            X-Credits-Charged:
              description: |
                Total number of API credits consumed. Equals credits per lookup
                multiplied by the count of valid IPs.
              schema:
                type: number
                example: 2
            X-Successful-Record:
              description: |
                Number of valid IP addresses that were successfully resolved in
                this bulk request. Invalid, bogon, and private IPs are not counted.
                This header is included only when at least one bulk entry returns an
                error message and total successful lookups are fewer than submitted
                entries.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BulkSecurityResponseItem"
              example:
                - ip: "2.56.188.34"
                  security:
                    threat_score: 80
                    is_tor: false
                    is_proxy: true
                    proxy_provider_names: [
                      "Zyte Proxy"
                    ]
                    proxy_confidence_score: 80
                    proxy_last_seen: "2025-12-12"
                    proxy_days_seen_30d: 4
                    proxy_days_seen_7d: 1
                    proxy_provider_count_30d: 1
                    is_residential_proxy: true
                    is_vpn: true
                    vpn_provider_names: [
                      "Nord VPN"
                    ]
                    vpn_confidence_score: 80
                    vpn_last_seen: "2026-01-19"
                    is_relay: false
                    relay_provider_name: ""
                    is_anonymous: true
                    is_known_attacker: true
                    is_bot: false
                    bot_confidence_score: 0
                    bot_operator_name: ""
                    bot_type: ""
                    is_known_good_bot: false
                    bot_last_seen: ""
                    is_spam: false
                    is_cloud_provider: true
                    cloud_provider_name: "Packethub S.A."
                    is_corporate_gateway: false
                    corporate_gateway_type: ""
                    corporate_gateway_provider_name: ""
                - message: "'10.0.0.1' is a bogon IP address."
        "400":
          description: |
            Bad request. Returned for the whole request only when the body is missing or not
            valid JSON, `ips` is missing, is not a JSON array, or is empty, or `ips` has more
            than 50,000 entries, or when special characters such as [ ] { } | ^ ` are
            present in the API URL, either in a parameter name or its value (especially in
            the API key). An invalid IP does not fail the request: that entry is returned as
            a `message` object inside the HTTP 200 array.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                specialCharacters:
                  summary: Special characters in API URL or key
                  value:
                    message: "Invalid character found in the request target."
                malformedJson:
                  summary: Malformed JSON body for bulk endpoint
                  value:
                    message: "Malformed JSON request or invalid field"
                missingIps:
                  summary: Bulk body missing ips field
                  value:
                    message: "IP addresses for bulk lookup are missing"
                ipsNotArray:
                  summary: Bulk ips field is not a JSON array
                  value:
                    message: "'ips' must be a JSON array of strings, e.g. {\"ips\": [\"value1\", \"value2\"]}"
                emptyBulkIps:
                  summary: Bulk ips array is empty
                  value:
                    message: "'ips' must not be empty or null"
                tooManyBulkEntries:
                  summary: Bulk body exceeds 50,000 entries
                  value:
                    message: "No. of lookup queries cannot be more than 50000"
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:

            - The `apiKey` URL parameter is missing.
            - An invalid (random or incorrect) API key is provided.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - The API request is made using an API key for a database subscription.
            - The subscription is in a 'paused' state.
            - The subscription trial has expired.
            - The bulk IP security lookup endpoint is called using a free subscription API key.
            - The bulk IP security lookup endpoint is called using Request Origin (CORS)
              authentication. Bulk requests require an `apiKey` and cannot be authenticated
              using Request Origin alone.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"

                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"

                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"

                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"

                databaseSubscriptionKey:
                  summary: Database subscription API key used for REST API
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."

                freePlanAccessBulk:
                  summary: Free subscription used for bulk IP Security lookup
                  value:
                    message: "Bulk IP Security Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."

                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."

                trialExpired:
                  summary: Subscription trial has expired
                  value:
                    message: "Your subscription trial has been expired. Please subscribe to a paid plan to use IPGeolocation API."

                requestOriginBulk:
                  summary: Bulk endpoint called using Request Origin authentication
                  value:
                    message: "Bulk queries are not allowed with request origins. Please use an API key to perform bulk queries."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "405":
          $ref: "#/components/responses/MethodNotAllowedBulk"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "415":
          $ref: "#/components/responses/UnsupportedMediaType"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

  /v3/asn:
    get:
      operationId: lookupASN
      security:
        - ApiKeyAuth: []
      summary: ASN Lookup
      description: |
        Returns ASN details for a single IPv4 address, IPv6 address,
        or ASN number.

        The response contains information about the Autonomous System
        responsible for routing the queried IP address or ASN.

        Basic ASN metadata is always returned, while additional routing
        relationships such as peers, upstreams, downstreams, routes,
        and WHOIS data can be retrieved using the `include` parameter.

        When the lookup is performed using the `asn` parameter,
        the `ip` field is not included in the response.

        Each successful lookup consumes **1 credit**.

        Use the `fields`, `excludes`, and `include` parameters
        to customize the response.

      tags:
        - ASN Lookup

      parameters:
        - name: ip
          in: query
          required: false
          description: |
            An IPv4 address or IPv6 address to look up. When omitted, the API
            resolves the public IP of the requesting client.

            If both `ip` and a non-empty `asn` are sent, the lookup uses `asn` and ignores `ip`
            (no error, and the response has no `ip` field).

            Empty or whitespace-only values are treated the same as omission and resolve
            the caller IP.

            Pass `ip` only once. If multiple `ip` query parameters are sent,
            values may be merged and treated as invalid input (HTTP 400).

          schema:
            type: string
            example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"


        - name: asn
          in: query
          required: false
          description: |
            An Autonomous System Number (ASN) to look up.

            When provided, the lookup is performed directly using the specified ASN.
            If both `ip` and a non-empty `asn` are sent, the lookup uses `asn` and ignores `ip`
            (no error, and the response has no `ip` field).

            The API returns detailed information about the ASN including the
            organization name, country of registration, ASN type, routing statistics,
            and other related network metadata.

            Pass `asn` only once. If multiple `asn` query parameters are sent,
            values may be merged and treated as invalid input (HTTP 400).

            Accepted numeric values (after stripping an optional `AS` prefix) range
            from 1 to 4294967295 (the full 32-bit ASN range per RFC 6793). A
            non-numeric value or a value outside this range returns HTTP 400
            (see the `invalidAsnQuery` example on the Bad Request response).

          schema:
            type: string
            example: "AS24940"

        - name: include
          in: query
          required: false
          description: |
            Comma-separated list of optional data modules to add to the response. These are
            not returned by default.

            Supported ASN modules include:

            - `peers`
            - `downstreams`
            - `upstreams`
            - `routes`
            - `whois_response`

            Use `*` (or `all`, `any`) to add all five modules. Values are case-sensitive; unknown values are ignored.

            If multiple values are provided, they must be comma-separated.

            For additional query parameters (`include`, `fields`, `excludes`, `output`),
            unknown values are ignored. The API still returns HTTP 200 and applies only
            recognized values.

          schema:
            type: string
            example: "peers,downstreams,upstreams,routes,whois_response"

        - name: fields
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to return. Everything else is omitted.
            The `ip` field is always returned when the lookup is performed using an IP address.

            Modules added with `include` are always kept, even when `fields` lists only some
            `asn` fields (e.g. `include=peers&fields=asn.as_number` returns `as_number` and
            `peers`). `fields` cannot add a module on its own. `*` anywhere in `fields` returns
            the full response. Fields inside `peers`, `upstreams`, `downstreams` and `routes`
            entries cannot be selected individually. Names are case-sensitive.

            Supports dot-notation for nested fields: `asn.organization`, `asn.domain`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins and
            it is left out of the response (e.g. `fields=asn.organization&excludes=asn.organization`
            drops `organization`). An object left with no fields is removed, so
            `fields=asn&excludes=asn` returns an empty object for an `asn` lookup, or only `ip` for an
            `ip` lookup.

            If you list both an object key and one of its nested fields separated by comma
            (e.g. `asn,asn.organization`), the full object is returned.

            Unknown names are ignored and the API still returns HTTP 200; if no name in
            `fields` is a real field, the full response is returned.

            The ASN lookup endpoint itself requires a paid plan; this parameter only
            applies once a request is authorized.

          schema:
            type: string
            example: "asn.organization,asn.country"

        - name: excludes
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to remove from the response.
            The `ip` field cannot be excluded.

            `excludes` also wins over `include`: `include=*&excludes=peers` (or
            `excludes=asn.peers`) returns every module except `peers`.

            Supports dot-notation for nested fields: `asn.domain`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins and
            it is left out of the response (e.g. `fields=asn.organization&excludes=asn.organization`
            drops `organization`). An object left with no fields is removed, so
            `fields=asn&excludes=asn` returns an empty object for an `asn` lookup, or only `ip` for an
            `ip` lookup.

            Unknown fields or object keys in `excludes` are ignored. The API still returns
            HTTP 200.

            The ASN lookup endpoint itself requires a paid plan; this parameter only
            applies once a request is authorized.

          schema:
            type: string
            example: "asn.date_allocated,asn.allocation_status"

        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json

      responses:
        "200":
          description: ASN information for the requested IP address.
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1

          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ASNLookupResponse"
              example:
                asn:
                  as_number: "AS24940"
                  organization: "Hetzner Online GmbH"
                  country: "DE"
                  type: "HOSTING"
                  domain: "hetzner.com"
                  date_allocated: "2002-06-03"
                  asn_name: "HETZNER-AS"
                  allocation_status: "ASSIGNED"
                  num_of_ipv4_routes: "84"
                  num_of_ipv6_routes: "6"
                  rir: "RIPE"
                  peers:
                    - as_number: "AS58057"
                      description: "Securebit A"
                      country: "CH"
                    - as_number: "AS28792"
                      description: "Public Internet Ltd"
                      country: "GB"
                  routes:
                    - "78.46.0.0/15"
                    - "138.199.128.0/17"
                  upstreams:
                    - as_number: "AS12552"
                      description: "GlobalConnect AB"
                      country: "SE"
                    - as_number: "AS58057"
                      description: "Securebit AG"
                      country: "CH"
                  downstreams:
                    - as_number: "AS209148"
                      description: "Securepoint GmbH"
                      country: "DE"
                    - as_number: "AS198167"
                      description: "Apptc.me s.r.o."
                      country: "CZ"
                  whois_response: |
                    #
                    # ARIN WHOIS data and services are subject to the Terms of Use
                    #
                    ASNumber:       24940
                    ASName:         HETZNER-AS
                    OrgName:        Hetzner Online GmbH
                    Country:        DE
                    ...
        "404":
          description: |
            Not found. Returned for one of the following reasons:

            - An IPv4 or IPv6 address has no ASN in the IPGeolocation database ("Provided IP Address '...' doesn't have an associated ASN in our database.").
            - A valid ASN does not exist in the database ("Provided ASN or IP Address '...' doesn't exist in our database.").
            - An IPv4, IPv6, or ASN is passed as a path variable
              instead of as a URL query parameter (e.g., using `/v3/asn/8.8.8.8`
              instead of `/v3/asn?ip=8.8.8.8`).
            - A non-existent or incorrect API endpoint is called.

            Invalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ipNotInDatabase:
                  summary: ASN not found in database
                  value:
                    message: "Provided ASN or IP Address 'AS4200000000' doesn't exist in our database."
                asnForIpNotFound:
                  summary: IP address has no associated ASN in the database
                  value:
                    message: "Provided IP Address 'IP_ADDRESS' doesn't have an associated ASN in our database."
                ipAsPathVariable:
                  summary: IP passed as path variable instead of query parameter
                  value:
                    message: "No endpoint GET /v3/asn/8.8.8.8."
                asnAsPathVariable:
                  summary: ASN passed as path variable instead of query parameter
                  value:
                    message: "No endpoint GET /v3/asn/24940."
                wrongEndpoint:
                  summary: Incorrect or non-existent endpoint
                  value:
                    message: "No endpoint GET /v3/asn-invalid."
        "400":
          description: |
            Bad request. Returned for one of the following reasons:
            - The provided IPv4 address or IPv6 address is invalid.
            - The provided `asn` value is non-numeric (once any `AS` prefix is stripped)
              or outside the accepted range of 1-4294967295.
            - Special characters such as [ ] { } | ^ ` are present in the API URL,
              either in a parameter name or its value (especially in the API key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidIp:
                  summary: Invalid IPv4/IPv6 input
                  value:
                    message: "Provided IP address '999.999.999.999' is not valid."
                invalidAsnQuery:
                  summary: Non-numeric or out-of-range ASN value
                  value:
                    message: "Provided ASN 'abc' is not valid."
                specialCharacters:
                  summary: Special characters in API URL or key
                  value:
                    message: "Invalid character found in the request target."
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:

            - An API key is required for this request, but the `apiKey` query parameter is
              missing and the request doesn't come from a domain added under Request Origin.
            - An invalid (random or incorrect) API key is provided, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - The API request is made using an API key for a database subscription.
            - The API request is made using a free subscription API key.
            - The subscription is in a 'paused' state.
            - The subscription trial has expired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscriptionKey:
                  summary: Database subscription API key used for REST API
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                freePlanAccess:
                  summary: Free subscription used for ASN lookup API
                  value:
                    message: "ASN API Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "423":
          $ref: "#/components/responses/Locked"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"


  /v3/abuse:
    get:
      operationId: lookupIpAbuseContact
      security:
        - ApiKeyAuth: []
      summary: IP Abuse Contact Lookup
      description: |
        Returns abuse contact information for a single IPv4 or IPv6 address.

        The response includes the organization responsible for handling abuse
        complaints related to the queried IP address. This typically contains
        the abuse contact name and kind, organization name, contact emails, phone
        numbers, and the registered address.

        This endpoint is intended for reporting malicious activities such as
        spam, phishing, DDoS attacks, and other network abuse.

        When only abuse contact information is required, using this endpoint is
        recommended instead of `/v3/ipgeo?include=abuse` because it returns a
        smaller response payload and predictable credit usage.

        Each successful lookup consumes **1 credit**.

        Use the `fields` and `excludes` parameters to control which parts of
        the response are returned.

      tags:
        - IP Abuse Contact

      parameters:
        - name: ip
          in: query
          required: false
          description: |
            An IPv4 address or IPv6 address to look up. When omitted, the API
            resolves the public IP of the requesting client. Empty or whitespace-only values
            are treated the same as omission and resolve caller IP. Pass `ip` only once. If multiple `ip` query parameters are sent,
            values may be merged and treated as invalid input (HTTP 400).
          schema:
            type: string
            example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"


        - name: fields
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to return. Everything else is omitted.
            The `ip` field is always returned regardless of this filter.

            Supports dot-notation for nested fields: `abuse.route`, `abuse.organization`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins
            and it is left out of the response (e.g. `fields=abuse.name&excludes=abuse.name` drops
            `name`). An object left with no fields is removed, so `fields=abuse&excludes=abuse`
            returns only `ip`.

            If you list both an object key and one of its nested fields separated by comma
            (e.g. `abuse,abuse.name`), the full object is returned.

            Unknown names are ignored and the API still returns HTTP 200; if no name in
            `fields` is a real field, the full response is returned.

            This parameter only has an effect once a request is authorized; the Abuse Contact
            API as a whole requires a paid plan.
          schema:
            type: string
            example: "abuse.name,abuse.organization"

        - name: excludes
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to remove from the response. The `ip`
            field cannot be excluded.

            Supports dot-notation for nested fields: `abuse.name`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins
            and it is left out of the response (e.g. `fields=abuse.name&excludes=abuse.name` drops
            `name`). An object left with no fields is removed, so `fields=abuse&excludes=abuse`
            returns only `ip`.

            Unknown fields or object keys in `excludes` are ignored. The API still returns
            HTTP 200.

            This parameter only has an effect once a request is authorized; the Abuse Contact
            API as a whole requires a paid plan.
          schema:
            type: string
            example: "abuse.address,abuse.emails"

        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json

      responses:
        "200":
          description: Abuse contact information for the requested IP address.
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1

          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AbuseLookupResponse"
              example:
                ip: "1.0.0.0"
                abuse:
                  route: "1.0.0.0/24"
                  country: "AU"
                  name: "IRT-APNICRANDNET-AU"
                  organization: ""
                  kind: "group"
                  address: "PO Box 3646, South Brisbane, QLD 4101, Australia"
                  emails:
                    - "helpdesk@apnic.net"
                  phone_numbers:
                    - "+61738583100"
        "404":
          description: |
            Not found. Returned for one of the following reasons:

            - A syntactically valid IPv4 or IPv6 address does not exist in the IPGeolocation database.
            - An IPv4 address or IPv6 address is passed as a path variable
              instead of as a URL query parameter (e.g., using `/v3/abuse/8.8.8.8`
              instead of `/v3/abuse?ip=8.8.8.8`).
            - A non-existent or incorrect API endpoint is called.

            Invalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ipNotInDatabase:
                  summary: IPv4/IPv6 not found in database
                  value:
                    message: "Provided IP Address 'IP_ADDRESS' doesn't exist in our database."
                ipAsPathVariable:
                  summary: IP passed as path variable instead of query parameter
                  value:
                    message: "No endpoint GET /v3/abuse/8.8.8.8."
                wrongEndpoint:
                  summary: Incorrect or non-existent endpoint
                  value:
                    message: "No endpoint GET /v3/abuse-invalid."
        "400":
          description: |
            Bad request. Returned for one of the following reasons:
            - The provided IPv4 address or IPv6 address is invalid.
            - Special characters such as [ ] { } | ^ ` are present in the API URL,
              either in a parameter name or its value (especially in the API key).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidIp:
                  summary: Invalid IPv4/IPv6 input
                  value:
                    message: "Provided IP address '999.999.999.999' is not valid."
                specialCharacters:
                  summary: Special characters in API URL or key
                  value:
                    message: "Invalid character found in the request target."
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:

            - An API key is required for this request, but the `apiKey` query parameter is
              missing and the request doesn't come from a domain added under Request Origin.
            - An invalid (random or incorrect) API key is provided, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - The API request is made using an API key for a database subscription.
            - The API request is made using a free subscription API key.
            - The subscription is in a 'paused' state.
            - The subscription trial has expired.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscriptionKey:
                  summary: Database subscription API key used for REST API
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                freePlanAccess:
                  summary: Free subscription used for Abuse Contact API
                  value:
                    message: "Abuse Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "423":
          $ref: "#/components/responses/Locked"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

  /v3/abuse-bulk:
    post:
      operationId: bulkLookupIpAbuseContact
      security:
        - ApiKeyAuth: []
      summary: Bulk IP Abuse Contact Lookup
      description: |
        Returns abuse contact information for up to **50,000 IPv4 or IPv6
        addresses** in a single request.

        The request body must contain an `ips` array.

        Each IP is processed independently, and surrounding spaces are trimmed. Invalid,
        empty, null, bogon, or private entries, and IPs with no abuse contact in the
        database, return an object containing only a `message` field; the rest of the
        request still succeeds.

        Credits are charged **per IP that returns abuse contact data**, using the same
        pricing as the single lookup endpoint (1 credit per IP).

        When the number of entries that returned abuse contact data is lower than the
        number of submitted entries, the response header `X-Successful-Record` gives
        that number.

        Bulk requests require an `apiKey`; they cannot be authenticated using Request
        Origin alone.

        Only the `POST` method is supported for this endpoint.
      tags:
        - IP Abuse Contact
      parameters:
        - name: fields
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to return. Everything else is omitted.
            The `ip` field is always returned regardless of this filter.

            Supports dot-notation for nested fields: `abuse.route`, `abuse.organization`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins
            and it is left out of the response (e.g. `fields=abuse.name&excludes=abuse.name` drops
            `name`). An object left with no fields is removed, so `fields=abuse&excludes=abuse`
            returns only `ip`.

            If you list both an object key and one of its nested fields separated by comma
            (e.g. `abuse,abuse.name`), the full object is returned.

            Unknown names are ignored and the API still returns HTTP 200; if no name in
            `fields` is a real field, the full response is returned.

            This parameter only has an effect once a request is authorized; the Abuse Contact
            API as a whole requires a paid plan.
          schema:
            type: string
            example: "abuse.name,abuse.organization"

        - name: excludes
          in: query
          required: false
          description: |
            Comma-separated list of fields or objects to remove from the response. The `ip`
            field cannot be excluded.

            Supports dot-notation for nested fields: `abuse.name`.

            If the same field or object is listed in both `fields` and `excludes`, `excludes` wins
            and it is left out of the response (e.g. `fields=abuse.name&excludes=abuse.name` drops
            `name`). An object left with no fields is removed, so `fields=abuse&excludes=abuse`
            returns only `ip`.

            Unknown fields or object keys in `excludes` are ignored. The API still returns
            HTTP 200.

            This parameter only has an effect once a request is authorized; the Abuse Contact
            API as a whole requires a paid plan.
          schema:
            type: string
            example: "abuse.address,abuse.emails"

        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json
      requestBody:
        required: true
        description: |
          A JSON object containing an `ips` array. Each element is a string representing
          an IPv4 address or IPv6 address. The array must not be empty and
          must not contain more than 50,000 entries.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkAbuseRequest"
            examples:
              mixedIps:
                summary: Mixed IPv4 and IPv6
                value:
                  ips:
                    - "1.0.0.0"
                    - "91.128.103.196"
                    - "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
              ipv4Only:
                summary: Multiple IPv4 addresses
                value:
                  ips:
                    - "1.0.0.0"
                    - "49.12.0.0"
      responses:
        "200":
          description: |
            An array of results, one per input IP address, in the same order as the
            request `ips` array.

            Successful entries return an abuse contact lookup object containing the IP
            address and its abuse contact information.

            Invalid, empty, null, private, or bogon entries, and IPs with no abuse contact
            in the database, return an object containing only a `message` field; the rest
            of the request still succeeds.

            The `X-Successful-Record` response header is returned only when the number
            of entries that returned abuse contact data is lower than the number of
            submitted entries, and gives that number.
          headers:
            X-Credits-Charged:
              description: |
                Total number of API credits consumed. Equals 1 credit multiplied by the
                count of IPs that returned abuse contact data.
              schema:
                type: number
                example: 1
            X-Successful-Record:
              description: |
                Number of IP addresses that returned abuse contact data in this bulk
                request. Entries returned as a `message` object are not counted. This
                header is included only when this number is lower than the number of
                submitted entries.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BulkAbuseResponseItem"
              example:
                - ip: "1.0.0.0"
                  abuse:
                    route: "1.0.0.0/24"
                    country: "AU"
                    name: "IRT-APNICRANDNET-AU"
                    organization: ""
                    kind: "group"
                    address: "PO Box 3646, South Brisbane, QLD 4101, Australia"
                    emails:
                      - "helpdesk@apnic.net"
                    phone_numbers:
                      - "+61738583100"
                - message: "'10.0.0.1' is a bogon IP address."
            application/xml:
              schema:
                type: array
                xml:
                  name: ArrayList
                  wrapped: true
                items:
                  $ref: "#/components/schemas/BulkAbuseResponseItem"
                  xml:
                    name: item
              example: |
                <ArrayList>
                  <item>
                    <ip>1.0.0.0</ip>
                    <abuse>
                        <route>1.0.0.0/24</route>
                        <country>AU</country>
                        <name>IRT-APNICRANDNET-AU</name>
                        <organization></organization>
                        <kind>group</kind>
                        <address>PO Box 3646, South Brisbane, QLD 4101, Australia</address>
                        <emails>helpdesk@apnic.net</emails>
                        <phone_numbers>+61738583100</phone_numbers>
                    </abuse>
                  </item>
                  <item>
                      <message>'10.0.0.1' is a bogon IP address.</message>
                  </item>
                </ArrayList>

        "400":
          description: |
            Bad request. Returned for the whole request only when the body is missing or not
            valid JSON, `ips` is missing, is not a JSON array, or is empty, or `ips` has more
            than 50,000 entries, or when special characters such as [ ] { } | ^ ` are
            present in the API URL, either in a parameter name or its value (especially in
            the API key). An invalid IP does not fail the request: that entry is returned as
            a `message` object inside the HTTP 200 array.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                specialCharacters:
                  summary: Special characters in API URL or key
                  value:
                    message: "Invalid character found in the request target."
                malformedJson:
                  summary: Malformed JSON body for bulk endpoint
                  value:
                    message: "Malformed JSON request or invalid field"
                missingIps:
                  summary: Bulk body missing ips field
                  value:
                    message: "IP addresses for bulk lookup are missing"
                ipsNotArray:
                  summary: Bulk ips field is not a JSON array
                  value:
                    message: "'ips' must be a JSON array of strings, e.g. {\"ips\": [\"value1\", \"value2\"]}"
                emptyBulkIps:
                  summary: Bulk ips array is empty
                  value:
                    message: "'ipList' must not be empty or null"
                tooManyBulkEntries:
                  summary: Bulk body exceeds 50,000 entries
                  value:
                    message: "No. of lookup queries cannot be more than 50000"
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:

            - The `apiKey` URL parameter is missing.
            - An invalid (random or incorrect) API key is provided.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - The API request is made using an API key for a database subscription.
            - The subscription is in a 'paused' state.
            - The subscription trial has expired.
            - The bulk abuse contact lookup endpoint is called using a free subscription API key.
            - The bulk abuse contact lookup endpoint is called using Request Origin (CORS)
              authentication. Bulk requests require an `apiKey` and cannot be authenticated
              using Request Origin alone.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscriptionKey:
                  summary: Database subscription API key used for REST API
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                freePlanAccessBulk:
                  summary: Free subscription used for bulk abuse contact lookup
                  value:
                    message: "Bulk Abuse Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
                trialExpired:
                  summary: Subscription trial has expired
                  value:
                    message: "Your subscription trial has been expired. Please subscribe to a paid plan to use IPGeolocation API."
                requestOriginBulk:
                  summary: Bulk endpoint called using Request Origin authentication
                  value:
                    message: "Bulk queries are not allowed with request origins. Please use an API key to perform bulk queries."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "405":
          $ref: "#/components/responses/MethodNotAllowedBulk"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "415":
          $ref: "#/components/responses/UnsupportedMediaType"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

  /v3/timezone:
    get:
      operationId: lookupTimezone
      security:
        - ApiKeyAuth: []
      summary: Timezone Lookup
      description: |
        Returns current date, time, and timezone information for a
        specific location or identifier.

        The timezone can be resolved using one of several inputs,
        including an IANA timezone name (`tz`), geographic coordinates
        (`lat` and `long`), location address (`location`), IPv4 or IPv6
        address (`ip`), airport codes (`iata_code` or `icao_code`), or
        a UN/LOCODE (`lo_code`).

        Depending on the lookup method used, additional contextual
        information may also be returned in the response:

        - `location` object for IP address or location queries
        - `airport_details` object for IATA or ICAO code queries
        - `lo_code_details` object for UN/LOCODE queries

        If multiple lookup parameters are provided in the same request,
        the API resolves the timezone using the following priority order:

        1. `tz`
        2. `lat` and `long`
        3. `location`
        4. `ip`
        5. `iata_code`
        6. `icao_code`
        7. `lo_code`

        The `ip` parameter is always validated, even when a higher-priority parameter is
        present. An invalid `ip` returns HTTP 400, and a bogon or private `ip` returns
        HTTP 423.

        If none of the lookup parameters are provided, the API resolves
        the timezone using the public IP address of the requesting client.

        Each successful lookup consumes **1 credit**.

      tags:
        - Timezone
      parameters:
        - name: ip
          in: query
          required: false
          description: |
            An IPv4 or IPv6 address to look up. Domain names are not supported; passing one
            fails validation as an invalid IP address. When omitted, the API resolves the
            public IP of the requesting client. Empty or whitespace-only values are treated
            the same as omission and resolve caller IP. Pass `ip` only once. If multiple `ip`
            query parameters are sent, values may be merged and treated as invalid input
            (HTTP 400).
          schema:
            type: string
            example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"

        - name: lang
          in: query
          required: false
          description: |
            Language code for translated location names. Defaults to `en`. Supported values:
            `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`. An
            unsupported value returns HTTP 400. On a Free plan, any value other than `en`
            returns HTTP 401.
          schema:
            type: string
            default: "en"
            enum:
              - en
              - de
              - ru
              - ja
              - fr
              - cn
              - es
              - cs
              - it
              - ko
              - fa
              - pt
              - ar


        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json

        - name: lo_code
          in: query
          required: false
          description: |
            UN/LOCODE used to determine the timezone of a city or location.

            The code consists of a two-letter country code followed by
            three alphanumeric characters representing the location.

            When used, the response includes a `lo_code_details` object
            alongside the `time_zone` object.
          schema:
            type: string
            example: "DEBER"

        - name: icao_code
          in: query
          required: false
          description: |
            Four-letter ICAO airport code in uppercase (e.g. `KATL`), used to determine the
            timezone of the airport location. Lowercase ICAO codes are rejected with HTTP 400.
            (IATA codes and UN/LOCODEs are case-insensitive.)

            When used, the response includes an `airport_details` object
            containing airport metadata alongside the `time_zone` object.
          schema:
            type: string
            example: "KATL"

        - name: iata_code
          in: query
          required: false
          description: |
            Three-letter IATA airport code used to determine the timezone
            of the airport location.

            When used, the response includes an `airport_details` object
            containing airport metadata alongside the `time_zone` object.
          schema:
            type: string
            example: "LHR"

        - name: long
          in: query
          required: false
          description: |
            Longitude coordinate of the location used to determine the
            timezone. Must be provided together with the `lat` parameter.
            If only one of `lat` or `long` is sent, both are ignored and the lookup falls
            back to the next parameter, or to the caller's IP.

            Valid longitude values range from **-180 to 180**.
          schema:
            type: number
            format: float
            example: -74.0060

        - name: lat
          in: query
          required: false
          description: |
            Latitude coordinate of the location used to determine the
            timezone. Must be provided together with the `long` parameter.
            If only one of `lat` or `long` is sent, both are ignored and the lookup falls
            back to the next parameter, or to the caller's IP.

            Valid latitude values range from **-90 to 90**.
          schema:
            type: number
            format: float
            example: 40.7128

        - name: location
          in: query
          required: false
          description: |
            Address or location name used to determine the timezone.

            Typically a city-level or region-level address such as
            `London, UK` or `New York, USA`.

            When this parameter is used, the API returns a `location`
            object containing geolocation details alongside the
            `time_zone` object.
          schema:
            type: string
            example: "Lahore, Pakistan"

        - name: tz
          in: query
          required: false
          description: |
            IANA timezone identifier, e.g. `Europe/London`. The value is case-sensitive on
            this endpoint. (On `/v3/timezone/convert`, `tz_from` and `tz_to` are
            case-insensitive.)

            When provided, the API returns the current date, time, and timezone
            metadata for the specified timezone.

            If multiple lookup parameters are provided in the same request,
            the `tz` parameter takes the highest priority. An `ip` sent with `tz` is
            still validated: an invalid IP returns HTTP 400 and a bogon or private IP
            returns HTTP 423.

            Example identifiers include `Europe/London`, `America/New_York`,
            and `Asia/Tokyo`.
          schema:
            type: string
            example: "Australia/Lord_Howe"


      responses:
        "200":
          description: "Successful response"
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimezoneLookupResponse'
              examples:
                ipLookup:
                  summary: Lookup by IP address (`ip` parameter or caller IP)
                  value:
                    ip: "49.12.0.0"
                    location:
                      continent_code: "EU"
                      continent_name: "Europe"
                      country_code2: "DE"
                      country_code3: "DEU"
                      country_name: "Germany"
                      country_name_official: "Federal Republic of Germany"
                      is_eu: true
                      state_prov: "Bavaria"
                      state_code: "DE-BY"
                      district: "Cham"
                      city: "Falkenstein"
                      zipcode: "93167"
                      latitude: "49.09745"
                      longitude: "12.48637"
                    time_zone:
                      name: "Europe/Berlin"
                      offset: 1
                      offset_with_dst: 1
                      date: "2026-03-07"
                      date_time: "2026-03-07 10:37:39"
                      date_time_txt: "Saturday, March 07, 2026 10:37:39"
                      date_time_wti: "Sat, 07 Mar 2026 10:37:39 +0100"
                      date_time_ymd: "2026-03-07T10:37:39+0100"
                      current_time: "2026-03-07 10:37:39.744+0100"
                      current_time_unix: 1772876259.744
                      time_24: "10:37:39"
                      time_12: "10:37:39 AM"
                      week: 10
                      month: 3
                      year: 2026
                      year_abbr: "26"
                      current_tz_abbreviation: "CET"
                      current_tz_full_name: "Central European Standard Time"
                      standard_tz_abbreviation: "CET"
                      standard_tz_full_name: "Central European Standard Time"
                      is_dst: false
                      dst_savings: 0
                      dst_exists: true
                      dst_tz_abbreviation: "CEST"
                      dst_tz_full_name: "Central European Summer Time"
                      dst_start:
                        utc_time: "2026-03-29 TIME 01:00"
                        duration: "+1.00H"
                        gap: true
                        date_time_after: "2026-03-29 TIME 03:00"
                        date_time_before: "2026-03-29 TIME 02:00"
                        overlap: false
                      dst_end:
                        utc_time: "2026-10-25 TIME 01:00"
                        duration: "-1.00H"
                        gap: false
                        date_time_after: "2026-10-25 TIME 02:00"
                        date_time_before: "2026-10-25 TIME 03:00"
                        overlap: true
                locationLookup:
                  summary: Lookup by location address (`location` parameter)
                  value:
                    location:
                      location_string: "London, UK"
                      country_name: "United Kingdom"
                      state_prov: "England"
                      city: "London"
                      locality: "Westminster"
                      latitude: "51.50002"
                      longitude: "-0.12240"
                    time_zone:
                      name: "Europe/London"
                      offset: 0
                      offset_with_dst: 1
                      date: "2026-07-07"
                      date_time: "2026-07-07 10:37:39"
                      date_time_txt: "Tuesday, July 07, 2026 10:37:39"
                      date_time_wti: "Tue, 07 Jul 2026 10:37:39 +0100"
                      date_time_ymd: "2026-07-07T10:37:39+0100"
                      current_time: "2026-07-07 10:37:39.744+0100"
                      current_time_unix: 1783845459.744
                      time_24: "10:37:39"
                      time_12: "10:37:39 AM"
                      week: 28
                      month: 7
                      year: 2026
                      year_abbr: "26"
                      current_tz_abbreviation: "BST"
                      current_tz_full_name: "British Summer Time"
                      standard_tz_abbreviation: "GMT"
                      standard_tz_full_name: "Greenwich Mean Time"
                      is_dst: true
                      dst_savings: 1
                      dst_exists: true
                      dst_tz_abbreviation: "BST"
                      dst_tz_full_name: "British Summer Time"
                      dst_start:
                        utc_time: "2026-03-29 TIME 01:00"
                        duration: "+1.00H"
                        gap: true
                        date_time_after: "2026-03-29 TIME 02:00"
                        date_time_before: "2026-03-29 TIME 01:00"
                        overlap: false
                      dst_end:
                        utc_time: "2026-10-25 TIME 01:00"
                        duration: "-1.00H"
                        gap: false
                        date_time_after: "2026-10-25 TIME 01:00"
                        date_time_before: "2026-10-25 TIME 02:00"
                        overlap: true
        "400":
          description: |
            Bad Request – Possible reasons include:
              - If the provided IPv4 or IPv6 address is invalid.

              - If special character(s) [ ] { } | ^ ` is passed in the API URL either as parameter or its value. Specially in case of API key.
            
              - If the provided IATA code to the request parameter `iata_code` is not in the format as three letter code AAA.
            
              - If the provided ICAO code to the request parameter `icao_code` is not in the format as four letter code AAAA.

              - If the provided UN/LOCODE to the request parameter `lo_code` is not in format as first two characters of country code, followed by the three alphanumeric characters of the city/region.
            
              - If the provided values to the request parameters `lat` and `long` are not numbers, or the values fall outside the acceptable latitude and longitude ranges. The valid range for latitude is between -90 and 90, and for longitude, it is between -180 and 180. Non-numeric values, and values written with an exponent larger than 50 (for example `1e51`), return `Invalid value '1e51' for parameter 'lat'.`

              - If the provided time zone name to the query parameter `tz` is wrong or not registered in the IANA time zone database.

              - An invalid or unsupported `lang` parameter is provided.

              - If the IPv4 or IPv6 address is not in our database and no other lookup parameter resolves a time zone (message: `Couldn't find time zone detail for the provided parameters.`), or the IP is found but has no time zone (message: `Couldn't find time zone detail for the IP address (IP)`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidIp:
                  summary: Invalid IPv4 or IPv6 address
                  value:
                    message: "'999.999.999.999' is not an IP string literal."
                specialCharacters:
                  summary: Invalid characters in request
                  value:
                    message: "Invalid character found in the request target."
                invalidIata:
                  summary: Invalid IATA code format
                  value:
                    message: "Invalid IATA code: LH. IATA code must be in the format of AAA."
                invalidIcao:
                  summary: Invalid ICAO code format
                  value:
                    message: "Invalid ICAO code: ATL. ICAO code must be in the format of AAAA."
                invalidLocode:
                  summary: Invalid UN/LOCODE format
                  value:
                    message: "Invalid LOCode: DER. LOCode must start with the first two characters as alphabets followed by three alphanumeric characters."
                invalidCoordinates:
                  summary: Coordinates out of range
                  value:
                    message: "'latitude' (40.7128) or 'longitude' (-700.0060) is not valid. 'latitude' must be between -90.0 and +90.0 and 'longitude' must be between -180.0 and +180.0."
                invalidNumber:
                  summary: Non-numeric coordinate value
                  value:
                    message: "Invalid value 'abc' for parameter 'lat'."
                invalidTimezone:
                  summary: Invalid timezone identifier
                  value:
                    message: "Check whether your input values are correct; time_zone_name = Europe/InvalidCity"
                invalidLang:
                  summary: Unsupported language parameter
                  value:
                    message: "This 'xx' lang is not valid. Please use 'en' as the default language"
                timezoneNotFound:
                  summary: No time zone found for the provided parameters
                  value:
                    message: "Couldn't find time zone detail for the provided parameters."

        "401":
          description: |
            Unauthorized – Possible reasons include:
              - An API key is required for this request, but the `apiKey` query parameter is missing and the request doesn't come from a domain added under Request Origin.
              - An invalid API key is provided, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
              - The account's email address has not been verified.
              - The account has been locked due to abuse or illegal activity.
              - When the request to Timezone API is made using API key for a database subscription
              - When the request to Timezone API is made on the 'paused' subscription.
              - If you’re making API requests after your subscription trial has been expired.
              - A language other than English is specified in the `lang` parameter
                while using a Free/Developer plan API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscription:
                  summary: Database subscription key used
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                pausedSubscription:
                  summary: Subscription paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
                freePlanLang:
                  summary: Non-English language requested on Free plan
                  value:
                    message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: |
            Not found. Returned for one of the following reasons:
            - If an IPv4 or IPv6 address is passed as a path variable instead of as a URL parameter (`ip=`).

            - If the location address provided to the `location` parameter is invalid. A city-level or state-level address must be provided.

            - If the provided UN/LOCODE, IATA code or ICAO code to the query parameters `lo_code`, `iata_code`, or `icao_code` does not exist in our database.

            - If the wrong endpoint is called, that does not exist in our API.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                ipAsPathVariable:
                  summary: IP passed as path variable instead of query parameter
                  value:
                    message: "No endpoint GET /v3/timezone/8.8.8.8."
                invalidLocation:
                  summary: Invalid location
                  value:
                    message: "We couldn't find the location (Germany, jaakjsdfjhb8wobv). Try a city or state level location address only."
                invalidAirportCode:
                  summary: Invalid IATA or ICAO airport code
                  value:
                    message: "'Data not found for the provided airport code: ZZZ Please contact at support@ipgeolocation.io if provided airport code exists.'"
                invalidLoCode:
                  summary: Invalid UN/LOCODE
                  value:
                    message: "'Data not found for the provided LO code: USZZZ Please contact at support@ipgeolocation.io if provided LO code exists.'"
                wrongEndpoint:
                  summary: Incorrect or non-existent endpoint
                  value:
                    message: "No endpoint GET /v3/timezone-invalid."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "423":
          $ref: "#/components/responses/Locked"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailableGeocoding"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"


  /v3/timezone/convert:
    get:
      operationId: convertTimezone
      security:
        - ApiKeyAuth: []
      summary: Timezone Time Conversion
      description: |
        Converts a given time between two timezones, locations,
        coordinates, airports, or UN/LOCODE identifiers.

        The conversion can be performed using one of the following
        parameter combinations:

        - `tz_from` and `tz_to`
        - `location_from` and `location_to`
        - `lat_from`, `long_from`, `lat_to`, `long_to`
        - `iata_from` and `iata_to`
        - `icao_from` and `icao_to`
        - `locode_from` and `locode_to`

        The optional `time` parameter specifies the time to convert.

        Supported formats: `yyyy-MM-dd`, `yyyy-MM-dd HH`, `yyyy-MM-dd HH:mm`,
        `yyyy-MM-dd HH:mm:ss`. Missing hour, minute or second parts default to `00`.
        The time is read as local time in the source time zone. If omitted, the
        current time in the source time zone is used.

        Each successful conversion request consumes **1 credit**.

      tags:
        - Timezone
      parameters:
        - name: tz_from
          in: query
          required: false
          description: |
            Source timezone identifier (IANA format) used for time conversion.
          schema:
            type: string
            example: "America/New_York"

        - name: tz_to
          in: query
          required: false
          description: |
            Destination timezone identifier (IANA format) used for time conversion.
          schema:
            type: string
            example: "Asia/Kabul"

        - name: time
          in: query
          required: false
          description: |
            Date and time to convert.

            Supported formats: `yyyy-MM-dd`, `yyyy-MM-dd HH`, `yyyy-MM-dd HH:mm`,
            `yyyy-MM-dd HH:mm:ss`. Missing hour, minute or second parts default to `00`.
            The time is read as local time in the source time zone. If omitted, the
            current time in the source time zone is used.
          schema:
            type: string
            example: "2025-01-30 09:00"

        - name: location_from
          in: query
          required: false
          description: |
            Source location address used to determine the source timezone.
          schema:
            type: string
            example: "New York, USA"

        - name: location_to
          in: query
          required: false
          description: |
            Destination location address used to determine the target timezone.
          schema:
            type: string
            example: "Lahore, Pakistan"

        - name: lat_from
          in: query
          required: false
          schema:
            type: number
            format: float
            example: 34.0207305

        - name: long_from
          in: query
          required: false
          schema:
            type: number
            format: float
            example: -118.6919163

        - name: lat_to
          in: query
          required: false
          schema:
            type: number
            format: float
            example: 53.4736827

        - name: long_to
          in: query
          required: false
          schema:
            type: number
            format: float
            example: -77.3977062

        - name: iata_from
          in: query
          required: false
          schema:
            type: string
            example: "DXB"

        - name: iata_to
          in: query
          required: false
          schema:
            type: string
            example: "LHR"

        - name: icao_from
          in: query
          required: false
          description: |
            Four-letter ICAO airport code in uppercase (e.g. `YSSY`) for the source
            airport. Lowercase ICAO codes are rejected with HTTP 400. (IATA codes and
            UN/LOCODEs are case-insensitive.)
          schema:
            type: string
            example: "YSSY"

        - name: icao_to
          in: query
          required: false
          description: |
            Four-letter ICAO airport code in uppercase (e.g. `ZBAA`) for the destination
            airport. Lowercase ICAO codes are rejected with HTTP 400. (IATA codes and
            UN/LOCODEs are case-insensitive.)
          schema:
            type: string
            example: "ZBAA"

        - name: locode_from
          in: query
          required: false
          schema:
            type: string
            example: "PKISB"

        - name: locode_to
          in: query
          required: false
          schema:
            type: string
            example: "USNYC"

        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json
      responses:
        "200":
          description: Successful response
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeConversionResponse'
              example:
                original_time: "2026-03-16 21:42:10"
                converted_time: "2026-03-16 22:42:10"
                diff_hour: 1
                diff_min: 60
        "400":
          description: |
            Bad Request – Possible reasons include:
              - If one of the query parameters `tz_from` and `tz_to` is provided and the other is missing, for time conversion.

              - If one of the query parameters `location_from` and `location_to` is provided and the other is missing, for time conversion.
            
              - If one of the query parameters `lat_from`, `long_from`, `lat_to`, and `long_to` is provided and other(s) is/are missing, for time conversion.
            
              - If the geographic coordinates provided to one of the parameters `lat_from`, `long_from`, `lat_to`, and `long_to` is/are not numbers, or the values fall outside the acceptable latitude and longitude ranges. The valid range for latitude is between -90 and 90, and for longitude, it is between -180 and 180. Non-numeric values, and values written with an exponent larger than 50 (for example `1e51`), return `Invalid value '1e51' for parameter 'lat_from'.`

              - If the value of `time` is not in one of the supported formats (`yyyy-MM-dd`, `yyyy-MM-dd HH`, `yyyy-MM-dd HH:mm`, `yyyy-MM-dd HH:mm:ss`). Example message: `Check whether your input values are correct; source_time_zone = America/New_York, destined_time_zone = Asia/Kabul, date_time = 30-01-2025`

              - If the time zone names provided to one of the parameters `tz_from` and `tz_to` is/are wrong or not registered in the IANA time zone database.

              - If one of the query parameters `iata_from` and `iata_to`, `icao_from` and `icao_to`, or `locode_from` and `locode_to` is provided and the other is missing, for time conversion.

              - If the value provided to `iata_from` or `iata_to` is not a three-letter code (AAA), to `icao_from` or `icao_to` is not a four-letter code (AAAA), or to `locode_from` or `locode_to` is not two country letters followed by three alphanumeric characters, for time conversion.

              - If none of the query parameter combination is provided for time conversion. `tz_from` and `tz_to` or `location_from` and `location_to` or `lat_from`, `long_from`, `lat_to`, `long_to` or `iata_from` and `iata_to` or `icao_from` and `icao_to` or `locode_from` and `locode_to` combination must be provided.

          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tzPairMissing:
                  summary: Missing tz_to parameter
                  value:
                    message: "To convert time by time zone names , both the tz_from and tz_to parameter must be provided. For more detail, you can read about it in the documentation at ipgeolocation.io or contact us at support@ipgeolocation.io."
                locationPairMissing:
                  summary: Missing location_to parameter
                  value:
                    message: "To convert time by Location , both the location_from and location_to parameter must be provided. For more detail, you can read about it in the documentation at ipgeolocation.io or contact us at support@ipgeolocation.io."
                coordinatePairMissing:
                  summary: Missing coordinate parameters
                  value:
                    message: "To convert time by coordinates , both the lat_from and long_from parameter must be provided. For more detail, you can read about it in the documentation at ipgeolocation.io or contact us at support@ipgeolocation.io."
                invalidCoordinates:
                  summary: Coordinates out of range
                  value:
                    message: "Provided  lat_to (450) or long_to (45) is not valid. Latitude must be between -90.0 and +90.0 and longitude must be between -180.0 and +180.0."
                invalidNumber:
                  summary: Non-numeric coordinate value
                  value:
                    message: "Invalid value 'abc' for parameter 'lat_from'."
                invalidTime:
                  summary: Unsupported time format
                  value:
                    message: "Check whether your input values are correct; source_time_zone = America/New_York, destined_time_zone = Asia/Kabul, date_time = 30-01-2025"
                invalidTimezone:
                  summary: Invalid timezone identifier
                  value:
                    message: "Check whether your input values are correct; source_time_zone = Europe/InvalidCity, destined_time_zone = Asia/Kabul, date_time = 2025-01-30 09:00"
                noConversionParams:
                  summary: Missing conversion parameters
                  value:
                    message: "Parameters' combination is not complete. 'tz_from' and 'tz_to' or 'location_from' and 'location_to' or 'lat_from' and 'long_from' and 'lat_to' and 'long_to' or 'locode_from' and 'locode_to' or 'iata_from' and 'iata_to' or 'icao_from' and 'icao_to' combinations must be provided."

        "401":
          description: |
            Unauthorized – Possible reasons include:
              - An API key is required for this request, but the `apiKey` query parameter is missing and the request doesn't come from a domain added under Request Origin.
              - An invalid API key is provided, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
              - The account's email address has not been verified.
              - The account has been locked due to abuse or illegal activity.
              - When the request to Timezone API is made using API key for a database subscription
              - When the request to Timezone API is made on the 'paused' subscription.
              - If you’re making API requests after your subscription trial has been expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                pausedSubscription:
                  summary: Subscription paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: |
            Not found. Returned for one of the following reasons:

            - If the provided UN/LOCODE, IATA code or ICAO code to one of the query
              parameters `locode_from`/`locode_to`, `iata_from`/`iata_to`, or
              `icao_from`/`icao_to` does not exist in our database.

            - If the address provided to `location_from` or `location_to` can't be
              resolved to a location. A city-level or state-level address must be provided.

            - If the wrong endpoint is called, that does not exist in our API.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidAirportCode:
                  summary: Invalid IATA or ICAO airport code
                  value:
                    message: "'Data not found for the provided airport code: ZZZ Please contact at support@ipgeolocation.io if provided airport code exists.'"
                invalidLoCode:
                  summary: Invalid UN/LOCODE
                  value:
                    message: "'Data not found for the provided LO code: USZZZ Please contact at support@ipgeolocation.io if provided LO code exists.'"
                invalidLocationFrom:
                  summary: Source location not found
                  value:
                    message: "We couldn't find the (from) location (Germany, jaakjsdfjhb8wobv). Try a city or state level address only."
                invalidLocationTo:
                  summary: Destination location not found
                  value:
                    message: "We couldn't find the (to) location (Germany, jaakjsdfjhb8wobv). Try a city or state level address only."
                wrongEndpoint:
                  summary: Incorrect or non-existent endpoint
                  value:
                    message: "No endpoint GET /v3/timezone/convert-invalid."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailableGeocoding"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

  /v3/user-agent:
    get:
      operationId: parseUserAgent
      security:
        - ApiKeyAuth: []
      summary: Parse User Agent String (auto-detect or explicit header)
      description: |
        Parses a user agent string and returns browser, device, and operating system
        details. Also detects bots, crawlers, and malicious or malformed user agent strings.

        This endpoint supports two usage modes:

        **Mode 1 — Caller's own user agent:**
        Don't set a custom `User-Agent` header. Browsers and most HTTP clients send one
        automatically, and the API parses it. If the request carries no `User-Agent`
        header at all, the API returns HTTP 400. This is the default browser behavior — when
        executed in browser JavaScript, the header is appended automatically and no
        additional configuration is needed.

        **Mode 2 — Explicit user agent header:**
        Pass any user agent string in the `User-Agent` request header. The API parses
        that string instead of detecting the caller's own user agent. Use this to
        simulate or test specific user agent strings server-side.

        Each successful lookup consumes **1 credit**.

      tags:
        - User Agent

      parameters:
        - name: User-Agent
          in: header
          required: false
          description: |
            The user agent string to parse. Browsers and most HTTP clients send their own
            `User-Agent` header automatically, and the API parses it; set the header to parse
            a different string. If the request carries no `User-Agent` header at all, the API
            returns HTTP 400.
          schema:
            type: string
          example: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"

        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json

      responses:
        "200":
          description: Parsed user agent details for the resolved user agent string.
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserAgentResponse"
              example:
                user_agent_string: "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"
                name: "Safari"
                type: "Browser"
                version: "9.0.2"
                version_major: "9"
                device:
                  name: "Apple Macintosh"
                  type: "Desktop"
                  brand: "Apple"
                  cpu: "Intel"
                engine:
                  name: "AppleWebKit"
                  type: "Browser"
                  version: "601.3.9"
                  version_major: "601"
                operating_system:
                  name: "Mac OS"
                  type: "Desktop"
                  version: "10.11.2"
                  version_major: "10.11"
                  build: "??"
        "400":
          description: |
            Bad Request. Returned for one of the following reasons:
            - Special characters [ ] { } | ^ ` are passed in the API URL (either in parameters or values), especially in the API key.
            - The `uaString` is empty or null when calling `/v3/user-agent`(POST).
            - The request body is not valid JSON (`Malformed JSON request or invalid field`)
              when calling `/v3/user-agent`(POST).
            - No `User-Agent` header is present when calling `GET /v3/user-agent`. Unlike the
              POST body, there is no alternative way to supply the string for this call, so a
              missing/blank header always fails validation.

            Request body validation (malformed JSON, a missing or blank `uaString`) runs before
            the API key is checked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                specialCharacters:
                  summary: Invalid special characters in request
                  value:
                    message: "Invalid character found in the request target."
                emptyUaString:
                  summary: Empty or null user agent string
                  value:
                    message: "User-Agent string must not be blank"
                missingUaStringHeader:
                  summary: Missing User-Agent header on GET
                  value:
                    message: "'userAgentString' must not be empty or null"
                malformedJson:
                  summary: Request body is not valid JSON
                  value:
                    message: "Malformed JSON request or invalid field"
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:
            - An API key is required for this request, but the `apiKey` query parameter is missing and the request doesn't come from a domain added under Request Origin.
            - The provided API key is not valid, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
            - The request is made using an API key of a database subscription.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - Requests are made after the subscription trial has expired.
            - The subscription is paused.
            - `POST /v3/user-agent` (custom user agent string in the request body) is called
              using a free subscription API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscriptionKey:
                  summary: Database subscription API key used
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                expiredTrial:
                  summary: Subscription trial expired
                  value:
                    message: "Your subscription trial has been expired. Please subscribe to a paid plan to use IPGeolocation API."
                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
                freePlanPaidFeature:
                  summary: Paid feature accessed on free plan
                  value:
                    message: "Custom User-Agent lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: |
            Not Found. Returned when an invalid or non-existent endpoint is called.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: "No endpoint GET /v3/user-agent-invalid."
        "405":
          $ref: "#/components/responses/MethodNotAllowedGetPost"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

    post:
      operationId: parseCustomUserAgent
      security:
        - ApiKeyAuth: []
      summary: Parse Custom User Agent String (payload)
      description: |
        Parses a custom user agent string supplied in the JSON request body and returns
        browser, device, and operating system details.

        **Mode 3 — Custom user agent string via POST body:**
        Pass the user agent string as the `uaString` field in a JSON payload. This is
        intended for server-side use cases where the string to be parsed is different
        from the caller's own user agent and is known at request time.

        This endpoint is available on **paid plans only**.

        Each successful lookup consumes **1 credit**.

      tags:
        - User Agent

      parameters:
        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json

      requestBody:
        required: true
        description: JSON body containing the custom user agent string to parse.
        content:
          application/json:
            schema:
              type: object
              required:
                - uaString
              properties:
                uaString:
                  type: string
                  description: The custom user agent string to parse.
                  example: "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"

      responses:
        "200":
          description: Parsed user agent details for the submitted user agent string.
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserAgentResponse"
              example:
                user_agent_string: "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"
                name: "Safari"
                type: "Browser"
                version: "9.0.2"
                version_major: "9"
                device:
                  name: "Apple Macintosh"
                  type: "Desktop"
                  brand: "Apple"
                  cpu: "Intel"
                engine:
                  name: "AppleWebKit"
                  type: "Browser"
                  version: "601.3.9"
                  version_major: "601"
                operating_system:
                  name: "Mac OS"
                  type: "Desktop"
                  version: "10.11.2"
                  version_major: "10.11"
                  build: "??"
        "400":
          description: |
            Bad Request. Returned for one of the following reasons:
            - Special characters [ ] { } | ^ ` are passed in the API URL (either in parameters or values), especially in the API key.
            - The `uaString` is empty or null when calling `/v3/user-agent`(POST).
            - The request body is not valid JSON (`Malformed JSON request or invalid field`)
              when calling `/v3/user-agent`(POST).
            - No `User-Agent` header is present when calling `GET /v3/user-agent`. Unlike the
              POST body, there is no alternative way to supply the string for this call, so a
              missing/blank header always fails validation.

            Request body validation (malformed JSON, a missing or blank `uaString`) runs before
            the API key is checked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                specialCharacters:
                  summary: Invalid special characters in request
                  value:
                    message: "Invalid character found in the request target."
                emptyUaString:
                  summary: Empty or null user agent string
                  value:
                    message: "User-Agent string must not be blank"
                missingUaStringHeader:
                  summary: Missing User-Agent header on GET
                  value:
                    message: "'userAgentString' must not be empty or null"
                malformedJson:
                  summary: Request body is not valid JSON
                  value:
                    message: "Malformed JSON request or invalid field"
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:
            - An API key is required for this request, but the `apiKey` query parameter is missing and the request doesn't come from a domain added under Request Origin.
            - The provided API key is not valid, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
            - The request is made using an API key of a database subscription.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - Requests are made after the subscription trial has expired.
            - The subscription is paused.
            - `POST /v3/user-agent` (custom user agent string in the request body) is called
              using a free subscription API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscriptionKey:
                  summary: Database subscription API key used
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                expiredTrial:
                  summary: Subscription trial expired
                  value:
                    message: "Your subscription trial has been expired. Please subscribe to a paid plan to use IPGeolocation API."
                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
                freePlanPaidFeature:
                  summary: Paid feature accessed on free plan
                  value:
                    message: "Custom User-Agent lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: |
            Not Found. Returned when an invalid or non-existent endpoint is called.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: "No endpoint GET /v3/user-agent-invalid."
        "405":
          $ref: "#/components/responses/MethodNotAllowedGetPost"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "415":
          $ref: "#/components/responses/UnsupportedMediaType"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"


  /v3/user-agent-bulk:
    post:
      operationId: parseUserAgentBulk
      security:
        - ApiKeyAuth: []
      summary: Bulk Parse User Agent Strings
      description: |
        Parses up to **50,000 user agent strings** in a single request.

        Pass a JSON body containing the `uaStrings` array. Each entry is parsed as sent.
        A `null` or blank entry fails the whole request with HTTP 400
        (`'userAgentString' must not be empty or null`) and nothing is charged. The total
        credits charged equals the number of strings in the array.

        This endpoint is available on **paid plans only**.

      tags:
        - User Agent

      parameters:
        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json

      requestBody:
        required: true
        description: JSON body containing the array of user agent strings to parse.
        content:
          application/json:
            schema:
              type: object
              required:
                - uaStrings
              properties:
                uaStrings:
                  type: array
                  description: |
                    Array of user agent strings to parse. Maximum 50,000 entries per request.
                  maxItems: 50000
                  items:
                    type: string
                  example:
                    - "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36"
                    - "Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+"
                    - "Mozilla/5.0 (Linux; U; en-US) AppleWebKit/528.5+ (KHTML, like Gecko, Safari/528.5+) Version/4.0 Kindle/3.0 (screen 600x800; rotate)"

      responses:
        "200":
          description: |
            Array of parsed user agent results, one object per submitted string,
            in the same order as the input array.
          headers:
            X-Credits-Charged:
              description: |
                Total number of API credits consumed by this request.
                Equals the number of user agent strings submitted.
              schema:
                type: number
                example: 3
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UserAgentResponse"
              example:
                - user_agent_string: "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36"
                  name: "Chrome"
                  type: "Browser"
                  version: "62.0.3202.84"
                  version_major: "62"
                  device:
                    name: "Samsung SM-G960F"
                    type: "Phone"
                    brand: "Samsung"
                    cpu: "Unknown"
                  engine:
                    name: "Blink"
                    type: "Browser"
                    version: "62.0"
                    version_major: "62"
                  operating_system:
                    name: "Android"
                    type: "Mobile"
                    version: "8.0.0"
                    version_major: "8"
                    build: "R16NW"
                - user_agent_string: "Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+"
                  name: "Kindle"
                  type: "Browser"
                  version: "3.0"
                  version_major: "3"
                  device:
                    name: "Amazon Kindle"
                    type: "eReader"
                    brand: "Amazon"
                    cpu: "ARMv7l"
                  engine:
                    name: "AppleWebKit"
                    type: "Browser"
                    version: "531.2"
                    version_major: "531"
                  operating_system:
                    name: "FireOS"
                    type: "Mobile"
                    version: "??"
                    version_major: "??"
                    build: "??"
                - user_agent_string: "Mozilla/5.0 (Linux; U; en-US) AppleWebKit/528.5+ (KHTML, like Gecko, Safari/528.5+) Version/4.0 Kindle/3.0 (screen 600x800; rotate)"
                  name: "Kindle"
                  type: "Browser"
                  version: "4.0"
                  version_major: "4"
                  device:
                    name: "Amazon Kindle"
                    type: "eReader"
                    brand: "Amazon"
                    cpu: "Unknown"
                  engine:
                    name: "AppleWebKit"
                    type: "Browser"
                    version: "528.5"
                    version_major: "528"
                  operating_system:
                    name: "FireOS"
                    type: "Mobile"
                    version: "??"
                    version_major: "??"
                    build: "??"
        "400":
          description: |
            Bad Request. Returned for one of the following reasons:
            - Special characters [ ] { } | ^ ` are passed in the API URL (either in parameters or values), especially in the API key.
            - The JSON body has no `uaStrings` field (or it is `null`). An empty array is not
              an error: it returns HTTP 200 with `[]` and 0 credits.
            - The `uaStrings` array contains a `null` or blank entry
              (`'userAgentString' must not be empty or null`). The whole request fails and
              nothing is charged.
            - More than 50,000 user agent strings are provided in a single bulk request.
            - The request body is not valid JSON (`Malformed JSON request or invalid field`) or
              `uaStrings` is not a JSON array of strings.

            Request body validation (malformed JSON, a missing `uaStrings` field, more than
            50,000 entries) runs before the API key is checked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                specialCharacters:
                  summary: Invalid special characters in request
                  value:
                    message: "Invalid character found in the request target."
                emptyBulkList:
                  summary: Missing uaStrings field
                  value:
                    message: "User-Agent strings for bulk lookup are missing"
                blankBulkEntry:
                  summary: Null or blank entry in uaStrings
                  value:
                    message: "'userAgentString' must not be empty or null"
                malformedJson:
                  summary: Request body is not valid JSON
                  value:
                    message: "Malformed JSON request or invalid field"
                uaStringsNotArray:
                  summary: uaStrings is not a JSON array of strings
                  value:
                    message: "'uaStrings' must be a JSON array of strings, e.g. {\"uaStrings\": [\"value1\", \"value2\"]}"
                bulkLimitExceeded:
                  summary: More than 50,000 strings in bulk request
                  value:
                    message: "No. of lookup queries cannot be more than 50000"
        "401":
          description: |
            Unauthorized. Returned for one of the following reasons:
            - The `apiKey` URL parameter is missing from the request.
            - The provided API key is not valid.
            - The request is made using an API key of a database subscription.
            - The account's email address has not been verified.
            - The account has been locked due to abuse or illegal activity.
            - Requests are made after the subscription trial has expired.
            - The subscription is paused.
            - The bulk user agent parsing endpoint is called using a free subscription API key.
            - The bulk user agent parsing endpoint is called using Request Origin (CORS) authentication. Bulk requests require an `apiKey`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscriptionKey:
                  summary: Database subscription API key used
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                expiredTrial:
                  summary: Subscription trial expired
                  value:
                    message: "Your subscription trial has been expired. Please subscribe to a paid plan to use IPGeolocation API."
                pausedSubscription:
                  summary: Subscription is paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
                bulkOnFreePlan:
                  summary: Bulk endpoint called with free subscription key
                  value:
                    message: "Bulk User-Agent lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
                requestOriginBulk:
                  summary: Bulk endpoint called with Request Origin authentication
                  value:
                    message: "Bulk queries are not allowed with request origins. Please use an API key to perform bulk queries."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: |
            Not Found. Returned when an invalid or non-existent endpoint is called.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                message: "No endpoint GET /v3/user-agent-bulk-invalid."
        "405":
          $ref: "#/components/responses/MethodNotAllowedBulk"
        "413":
          $ref: "#/components/responses/PayloadTooLarge"
        "415":
          $ref: "#/components/responses/UnsupportedMediaType"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

  /v3/astronomy:
    get:
      operationId: lookupAstronomy
      security:
        - ApiKeyAuth: []
      summary: Astronomy Lookup
      description: |
        Returns astronomical information for a specific location and date,
        including:

        - Sunrise and sunset times
        - Moonrise and moonset times
        - Morning and evening twilight phases (astronomical, nautical, civil)
        - Golden hour and blue hour windows (morning and evening)
        - Solar noon, day length, and astronomical midnight
        - Sun position: altitude, azimuth, distance from Earth
        - Moon position: altitude, azimuth, distance from Earth, parallactic angle
        - Moon phase, illumination percentage, and moon phase angle (`moon_angle`)

        The location can be resolved using geographic coordinates (`lat` and
        `long`), a location address (`location`), or an IP address (`ip`).

        If multiple lookup parameters are provided, the API resolves the
        location using the following priority order:

        1. `lat` and `long`
        2. `location`
        3. `ip`

        The `ip` parameter is always validated, even when a higher-priority parameter is
        present. An invalid `ip` returns HTTP 400, and a bogon or private `ip` returns
        HTTP 423.

        If none of the lookup parameters are provided, the API resolves the
        location using the public IP address of the requesting client.

        By default, results are calculated for the current date. Pass the
        `date` parameter to retrieve data for a specific date.

        Each successful lookup consumes **1 credit**.

      tags:
        - Astronomy
      parameters:
        - name: lat
          in: query
          required: false
          description: |
            Latitude coordinate of the location. Must be provided together with
            the `long` parameter.

            Valid latitude values range from **-90 to 90**.
          schema:
            type: number
            format: float
            example: -27.4748

        - name: long
          in: query
          required: false
          description: |
            Longitude coordinate of the location. Must be provided together with
            the `lat` parameter.

            Valid longitude values range from **-180 to 180**.
          schema:
            type: number
            format: float
            example: 153.017

        - name: location
          in: query
          required: false
          description: |
            Address or location name used to determine the astronomical
            information. Typically a city-level or region-level address such as
            `New York, USA` or `London, UK`.

            When this parameter is used, the API returns a `location` object
            containing geolocation details alongside the `astronomy` object.
          schema:
            type: string
            example: "London, UK"

        - name: ip
          in: query
          required: false
          description: |
            An IPv4 or IPv6 address used to resolve the location for the
            astronomical lookup. When omitted, the API resolves the public IP
            of the requesting client.

            When the lookup is performed using an IP address, the response
            includes additional geolocation fields in the `location` object
            such as continent, country codes, district, and zipcode.
          schema:
            type: string
            example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"

        - name: date
          in: query
          required: false
          description: |
            Date for which to retrieve astronomical information.

            Must be in `yyyy-MM-dd` format. Defaults to the current date if
            not provided. All astronomical information is calculated at the
            current time of day in the location's time zone, or in `time_zone` when
            that parameter is given. Without `date`, the current date is also taken in
            that time zone.
          schema:
            type: string
            format: date
            example: "2026-03-18"

        - name: elevation
          in: query
          required: false
          description: |
            Elevation of the location above sea level in meters. Used to
            refine astronomical calculations.

            When not provided, the elevation of the nearest known city to the
            resolved coordinates is used automatically; it falls back to `0`
            only when no elevation data is available for that location.
            Maximum allowed value is **10,000 meters**; only this upper bound
            is enforced (HTTP 400 if exceeded). Negative values are accepted
            without an error.
          schema:
            type: number
            format: double
            maximum: 10000
            example: 1500

        - name: time_zone
          in: query
          required: false
          description: |
            IANA timezone identifier used to convert all astronomical event
            timestamps into the specified timezone.

            When provided, all event times (sunrise, sunset, moonrise, moonset,
            twilight phases, solar noon, etc.) are returned as full date-time
            values (`yyyy-MM-dd HH:mm`) instead of time-only values (`HH:mm`),
            and a `time_zone` field is included in the `astronomy` object.

            The geographic location used for astronomical calculations remains
            unchanged. Only the timestamp representation is converted.

            Example: `Europe/London`, `America/New_York`, `Asia/Karachi`.
          schema:
            type: string
            example: "America/New_York"

        - name: lang
          in: query
          required: false
          description: |
            Language code for translated location names in the `location` object.
            Only applies when the lookup is performed via an IP address.

            Defaults to `en`. Non-English responses require a paid plan.
            Requesting a non-English `lang` value on a Free/Developer plan
            returns HTTP 401 (see the `freePlanLang` example under the 401
            response) rather than silently falling back to English. Unsupported
            `lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`. Defaults to `en`.
          schema:
            type: string
            default: "en"
            enum:
              - en
              - de
              - ru
              - ja
              - fr
              - cn
              - es
              - cs
              - it
              - ko
              - fa
              - pt
              - ar
        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json


      responses:
        "200":
          description: Successful response
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AstronomyLookupResponse'
              example:
                location:
                  latitude: "40.76473"
                  longitude: "-74.00084"
                  country_name: "United States"
                  state_prov: "New York"
                  city: "New York"
                  locality: "Midtown West"
                  elevation: "9"
                astronomy:
                  date: "2026-03-18"
                  current_time: "10:15:00.000"
                  mid_night: "00:06"
                  night_end: "04:49"
                  morning:
                    astronomical_twilight_begin: "04:49"
                    astronomical_twilight_end: "05:21"
                    nautical_twilight_begin: "05:21"
                    nautical_twilight_end: "05:53"
                    civil_twilight_begin: "05:53"
                    civil_twilight_end: "06:20"
                    blue_hour_begin: "05:42"
                    blue_hour_end: "06:03"
                    golden_hour_begin: "06:03"
                    golden_hour_end: "06:57"
                  sunrise: "06:20"
                  sunset: "19:00"
                  evening:
                    golden_hour_begin: "18:23"
                    golden_hour_end: "19:16"
                    blue_hour_begin: "19:16"
                    blue_hour_end: "19:38"
                    civil_twilight_begin: "19:00"
                    civil_twilight_end: "19:27"
                    nautical_twilight_begin: "19:27"
                    nautical_twilight_end: "19:59"
                    astronomical_twilight_begin: "19:59"
                    astronomical_twilight_end: "20:31"
                  night_begin: "20:31"
                  sun_status: "-"
                  solar_noon: "12:40"
                  day_length: "12:40"
                  sun_altitude: 42.5
                  sun_distance: 148900000.0
                  sun_azimuth: 150.3
                  moon_phase: "WAXING_CRESCENT"
                  moonrise: "08:45"
                  moonset: "22:10"
                  moon_status: "-"
                  moon_altitude: 15.2
                  moon_distance: 384400.0
                  moon_azimuth: 220.5
                  moon_parallactic_angle: 30.1
                  moon_illumination_percentage: "25.40"
                  moon_angle: 357.01
        "400":
          description: |
            Bad Request – Possible reasons include:
              - If the provided IPv4 or IPv6 address is invalid.
              - If special character(s) `[ ] { } | ^ \`` is passed in the
                API URL either as a parameter or its value, especially in the
                case of an API key.
              - If the provided `date` is not in the format `yyyy-MM-dd`.
              - If an invalid or unsupported `lang` parameter is provided.
              - If only one of `lat` or `long` is provided; both must be
                provided together.
              - If the provided values for `lat` and `long` are not numbers,
                or fall outside the acceptable ranges. Valid latitude range is
                **-90 to 90**; valid longitude range is **-180 to 180**.
                Non-numeric values, and values written with an exponent larger
                than 50 (for example `1e51`), return `Invalid value '1e51' for
                parameter 'lat'.` This also applies to a non-numeric `elevation`.
              - If the provided `elevation` value exceeds the maximum allowed
                value of **10,000 meters**.
              - If the provided `time_zone` is invalid or unrecognized.
              - If the provided IPv4 or IPv6 address does not exist in our
                database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidIp:
                  summary: Invalid IPv4 or IPv6 address
                  value:
                    message: "'999.999.999.999' is not an IP string literal."
                specialCharacters:
                  summary: Invalid characters in request
                  value:
                    message: "Invalid character found in the request target."
                invalidDate:
                  summary: Invalid date format
                  value:
                    message: "You must provide date in the 'yyyy-MM-dd' format"
                missingLat:
                  summary: Only 'long' provided, 'lat' missing
                  value:
                    message: "'lat' must not be null"
                missingLong:
                  summary: Only 'lat' provided, 'long' missing
                  value:
                    message: "'long' must not be null"
                invalidLatitude:
                  summary: Latitude out of range
                  value:
                    message: "Latitude must be between -90 and 90."
                invalidLongitude:
                  summary: Longitude out of range
                  value:
                    message: "Longitude must be between -180 and 180."
                invalidNumber:
                  summary: Non-numeric coordinate value
                  value:
                    message: "Invalid value 'abc' for parameter 'lat'."
                invalidElevation:
                  summary: Elevation exceeds maximum
                  value:
                    message: "Elevation cannot be greater than 10000 meters."
                invalidTimezone:
                  summary: Invalid timezone identifier
                  value:
                    message: "Check whether your input value is correct; time_zone_name = Europe/InvalidCity"
                invalidLang:
                  summary: Unsupported language parameter
                  value:
                    message: "This 'xx' lang is not valid. Please use 'en' as the default language"
                ipNotInDatabase:
                  summary: IP not found in database
                  value:
                    message: "Couldn't find astronomy detail for the IP address (IP_ADDRESS)"

        "401":
          description: |
            Unauthorized – Possible reasons include:
              - An API key is required for this request, but the `apiKey` query
                parameter is missing and the request doesn't come from a domain
                added under Request Origin.
              - An invalid API key is provided, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
              - The account's email address has not been verified.
              - The account has been locked due to abuse or illegal activity.
              - When the request is made using an API key for a database
                subscription.
              - When the request is made on a paused subscription.
              - If you are making API requests after your subscription trial
                has expired.
              - A language other than English is specified in the `lang`
                parameter while using a Free/Developer plan API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscription:
                  summary: Database subscription key used
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                pausedSubscription:
                  summary: Subscription paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
                freePlanLang:
                  summary: Non-English language on Free plan
                  value:
                    message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: |
            Not Found. Returned for one of the following reasons:
              - If the IPv4 or IPv6 address is passed as a path variable instead
                of as a URL parameter (`ip=`).
              - If the location address provided to the `location` parameter is
                invalid. A city-level or state-level address must be provided.
              - If the wrong endpoint is called that does not exist in the API.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidLocation:
                  summary: Invalid location address
                  value:
                    message: "We couldn't find the location (InvalidCity, XX). Try a city or state level location address only."
                wrongEndpoint:
                  summary: Incorrect or non-existent endpoint
                  value:
                    message: "No endpoint GET /v3/astronomy-invalid."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "423":
          $ref: "#/components/responses/Locked"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailableGeocoding"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"


  /v3/astronomy/timeSeries:
    get:
      operationId: lookupAstronomyTimeSeries
      security:
        - ApiKeyAuth: []
      summary: Astronomy Time Series Lookup
      description: |
        Returns daily astronomical information for a specific location across
        a date range.

        The response contains an array of daily astronomy records, each
        including sunrise, sunset, moonrise, moonset, twilight phases,
        solar noon, day length, and moon phase. Real-time positional data
        (altitude, azimuth, distance) is not included in time series
        responses.

        The location can be resolved using geographic coordinates (`lat` and
        `long`), a location address (`location`), or an IP address (`ip`).

        **Date range constraints:**
        - Both `dateStart` and `dateEnd` are required.
        - The range can cover at most **90 days**, counting both `dateStart` and
          `dateEnd` (so `dateEnd` can be at most 89 days after `dateStart`). `dateEnd`
          must not be before `dateStart`.
        - Both past and future dates are supported within the 90-day window.

        Each successful lookup consumes **1 credit** per request.

      tags:
        - Astronomy
      parameters:
        - name: lat
          in: query
          required: false
          description: |
            Latitude coordinate of the location. Must be provided together with
            the `long` parameter.

            Valid latitude values range from **-90 to 90**.
          schema:
            type: number
            format: float
            example: -27.4748

        - name: long
          in: query
          required: false
          description: |
            Longitude coordinate of the location. Must be provided together with
            the `lat` parameter.

            Valid longitude values range from **-180 to 180**.
          schema:
            type: number
            format: float
            example: 153.017

        - name: location
          in: query
          required: false
          description: |
            Address or location name used to determine the astronomical
            information. Typically a city-level or region-level address such as
            `New York, USA` or `London, UK`.

            When this parameter is used, the API returns a `location` object
            containing geolocation details alongside the `astronomy` object.
          schema:
            type: string
            example: "London, UK"

        - name: ip
          in: query
          required: false
          description: |
            An IPv4 or IPv6 address used to resolve the location for the
            astronomical lookup. When omitted, the API resolves the public IP
            of the requesting client.

            When the lookup is performed using an IP address, the response
            includes additional geolocation fields in the `location` object
            such as continent, country codes, district, and zipcode.
          schema:
            type: string
            example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"

        - name: dateStart
          in: query
          required: true
          description: |
            Start date of the time series range.

            Must be in `yyyy-MM-dd` format. The range can cover at most **90 days**,
            counting both `dateStart` and `dateEnd` (so `dateEnd` can be at most 89 days
            after `dateStart`).
          schema:
            type: string
            format: date
            example: "2026-03-18"

        - name: dateEnd
          in: query
          required: true
          description: |
            End date of the time series range.

            Must be in `yyyy-MM-dd` format. The range can cover at most **90 days**,
            counting both `dateStart` and `dateEnd` (so `dateEnd` can be at most 89 days
            after `dateStart`). `dateEnd` must not be before `dateStart`.
          schema:
            type: string
            format: date
            example: "2026-04-18"

        - name: elevation
          in: query
          required: false
          description: |
            Elevation of the location above sea level in meters. Used to
            refine astronomical calculations.

            When not provided, the elevation of the nearest known city to the
            resolved coordinates is used automatically; it falls back to `0`
            only when no elevation data is available for that location.
            Maximum allowed value is **10,000 meters**; only this upper bound
            is enforced (HTTP 400 if exceeded). Negative values are accepted
            without an error.
          schema:
            type: number
            format: double
            maximum: 10000
            example: 1500

        - name: time_zone
          in: query
          required: false
          description: |
            IANA timezone identifier used to convert all astronomical event
            timestamps into the specified timezone.

            When provided, all event times (sunrise, sunset, moonrise, moonset,
            twilight phases, solar noon, etc.) are returned as full date-time
            values (`yyyy-MM-dd HH:mm`) instead of time-only values (`HH:mm`),
            and a `time_zone` field is included in the `astronomy` object.

            The geographic location used for astronomical calculations remains
            unchanged. Only the timestamp representation is converted.

            Example: `Europe/London`, `America/New_York`, `Asia/Karachi`.
          schema:
            type: string
            example: "America/New_York"

        - name: lang
          in: query
          required: false
          description: |
            Language code for translated location names in the `location` object.
            Only applies when the lookup is performed via an IP address.

            Defaults to `en`. Non-English responses require a paid plan.
            Requesting a non-English `lang` value on a Free/Developer plan
            returns HTTP 401 (see the `freePlanLang` example under the 401
            response) rather than silently falling back to English. Unsupported
            `lang` values return HTTP 400 on `/v3/astronomy`. On
            `/v3/astronomy/timeSeries` the value is not validated: on paid plans an
            unsupported value returns English names, and on a Free plan any value other
            than `en` returns HTTP 401. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`. Defaults to `en`.
          schema:
            type: string
            default: "en"
            enum:
              - en
              - de
              - ru
              - ja
              - fr
              - cn
              - es
              - cs
              - it
              - ko
              - fa
              - pt
              - ar
        - name: output
          in: query
          required: false
          description: |
            Desired response format. Defaults to `json` if not specified. You can also
            control the format using the `Accept` header (`application/json`,
            `application/xml`, or `text/xml`). For successful responses and authentication
            errors, the `Accept` header takes precedence if both are provided: `output` is
            used only when the `Accept` header is absent or set to `*/*`, and an `Accept`
            value other than `application/xml` or `text/xml` (for example a browser's
            default) returns JSON even with `output=xml`. Values are matched exactly (use
            lowercase `xml`).

            If `output` is unknown or unsupported, it is ignored and the response defaults
            to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
          schema:
            type: string
            enum: [json, xml]
            default: json


      responses:
        "200":
          description: Successful response
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AstronomyTimeSeriesResponse'
              example:
                location:
                  latitude: "40.76473"
                  longitude: "-74.00084"
                  country_name: "United States"
                  state_prov: "New York"
                  city: "New York"
                  locality: "Midtown West"
                  elevation: "9"
                astronomy:
                  - date: "2026-03-18"
                    mid_night: "00:06"
                    night_end: "04:49"
                    morning:
                      astronomical_twilight_begin: "04:49"
                      astronomical_twilight_end: "05:21"
                      nautical_twilight_begin: "05:21"
                      nautical_twilight_end: "05:53"
                      civil_twilight_begin: "05:53"
                      civil_twilight_end: "06:20"
                      blue_hour_begin: "05:42"
                      blue_hour_end: "06:03"
                      golden_hour_begin: "06:03"
                      golden_hour_end: "06:57"
                    sunrise: "06:20"
                    sunset: "19:00"
                    evening:
                      golden_hour_begin: "18:23"
                      golden_hour_end: "19:16"
                      blue_hour_begin: "19:16"
                      blue_hour_end: "19:38"
                      civil_twilight_begin: "19:00"
                      civil_twilight_end: "19:27"
                      nautical_twilight_begin: "19:27"
                      nautical_twilight_end: "19:59"
                      astronomical_twilight_begin: "19:59"
                      astronomical_twilight_end: "20:31"
                    night_begin: "20:31"
                    sun_status: "-"
                    solar_noon: "12:40"
                    day_length: "12:40"
                    moon_phase: "WAXING_CRESCENT"
                    moonrise: "08:45"
                    moonset: "22:10"
                    moon_status: "-"
                  - date: "2026-03-19"
                    mid_night: "00:06"
                    night_end: "04:47"
                    morning:
                      astronomical_twilight_begin: "04:47"
                      astronomical_twilight_end: "05:19"
                      nautical_twilight_begin: "05:19"
                      nautical_twilight_end: "05:51"
                      civil_twilight_begin: "05:51"
                      civil_twilight_end: "06:18"
                      blue_hour_begin: "05:40"
                      blue_hour_end: "06:01"
                      golden_hour_begin: "06:01"
                      golden_hour_end: "06:55"
                    sunrise: "06:18"
                    sunset: "19:02"
                    evening:
                      golden_hour_begin: "18:25"
                      golden_hour_end: "19:18"
                      blue_hour_begin: "19:18"
                      blue_hour_end: "19:40"
                      civil_twilight_begin: "19:02"
                      civil_twilight_end: "19:29"
                      nautical_twilight_begin: "19:29"
                      nautical_twilight_end: "20:01"
                      astronomical_twilight_begin: "20:01"
                      astronomical_twilight_end: "20:33"
                    night_begin: "20:33"
                    sun_status: "-"
                    solar_noon: "12:40"
                    day_length: "12:44"
                    moon_phase: "WAXING_CRESCENT"
                    moonrise: "09:30"
                    moonset: "23:05"
                    moon_status: "-"
        "400":
          description: |
            Bad Request – Possible reasons include:
              - If the provided IPv4 or IPv6 address is invalid.
              - If special character(s) `[ ] { } | ^ \`` is passed in the
                API URL either as a parameter or its value.
              - If `dateStart` or `dateEnd` is not in the format `yyyy-MM-dd`.
              - If `dateEnd` is before `dateStart` (`End date must be on or after start date.`)
              - If `dateStart` or `dateEnd` is missing (`Required request parameter 'dateStart' is missing`) or empty.
              - If the range covers more than **90 days**, counting both
                `dateStart` and `dateEnd`.
              - If only one of `lat` or `long` is provided; both must be
                provided together.
              - If the provided values for `lat` and `long` are not numbers,
                or fall outside the acceptable ranges. Non-numeric values, and
                values written with an exponent larger than 50 (for example
                `1e51`), return `Invalid value '1e51' for parameter 'lat'.`
              - If the provided `elevation` value exceeds **10,000 meters**.
              - If the provided `time_zone` is invalid or unrecognized.
              - If the provided IPv4 or IPv6 address does not exist in our
                database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidIp:
                  summary: Invalid IPv4 or IPv6 address
                  value:
                    message: "'999.999.999.999' is not an IP string literal."
                specialCharacters:
                  summary: Invalid characters in request
                  value:
                    message: "Invalid character found in the request target."
                invalidDateFormat:
                  summary: Invalid date format
                  value:
                    message: "`dateStart` must be in 'yyyy-MM-dd' format"
                endBeforeStart:
                  summary: dateEnd is before dateStart
                  value:
                    message: "End date must be on or after start date."
                missingDateStart:
                  summary: dateStart is missing
                  value:
                    message: "Required request parameter 'dateStart' is missing"
                dateRangeExceeded:
                  summary: Date range exceeds 90 days
                  value:
                    message: "Date range cannot exceed 90 days."
                missingLat:
                  summary: Only 'long' provided, 'lat' missing
                  value:
                    message: "'lat' must not be null"
                missingLong:
                  summary: Only 'lat' provided, 'long' missing
                  value:
                    message: "'long' must not be null"
                invalidLatitude:
                  summary: Latitude out of range
                  value:
                    message: "Latitude must be between -90 and 90."
                invalidLongitude:
                  summary: Longitude out of range
                  value:
                    message: "Longitude must be between -180 and 180."
                invalidElevation:
                  summary: Elevation exceeds maximum
                  value:
                    message: "Elevation cannot be greater than 10000 meters."
                invalidTimezone:
                  summary: Invalid timezone identifier
                  value:
                    message: "Check whether your input value is correct; time_zone_name = Europe/InvalidCity"
                ipNotInDatabase:
                  summary: IP not found in database
                  value:
                    message: "Couldn't find astronomy detail for the IP address (IP_ADDRESS)"

        "401":
          description: |
            Unauthorized – Possible reasons include:
              - An API key is required for this request, but the `apiKey` query
                parameter is missing and the request doesn't come from a domain
                added under Request Origin.
              - An invalid API key is provided, or the request has no API key and its `Origin` or `Referer` domain is not registered as a Request Origin.
              - The account's email address has not been verified.
              - The account has been locked due to abuse or illegal activity.
              - When the request is made using an API key for a database
                subscription.
              - When the request is made on a paused subscription.
              - If your subscription trial has expired.
              - A language other than English is specified in the `lang`
                parameter while using a Free/Developer plan API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingApiKey:
                  summary: Missing API key
                  value:
                    message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
                invalidApiKey:
                  summary: Invalid API key
                  value:
                    message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
                unverifiedEmail:
                  summary: Email address not verified
                  value:
                    message: "Please verify your email before using IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
                databaseSubscription:
                  summary: Database subscription key used
                  value:
                    message: "You cannot query IPGeolocation API on a database plan subscription."
                pausedSubscription:
                  summary: Subscription paused
                  value:
                    message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
                freePlanLang:
                  summary: Non-English language on Free plan
                  value:
                    message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: |
            Not Found. Returned for one of the following reasons:
              - If the IPv4 or IPv6 address is passed as a path variable instead
                of as a URL parameter (`ip=`).
              - If the location address provided to the `location` parameter is
                invalid. A city-level or state-level address must be provided.
              - If the wrong endpoint is called that does not exist in the API.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidLocation:
                  summary: Invalid location address
                  value:
                    message: "We couldn't find the location (InvalidCity, XX). Try a city or state level location address only."
                wrongEndpoint:
                  summary: Incorrect or non-existent endpoint
                  value:
                    message: "No endpoint GET /v3/astronomy-invalid."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "423":
          $ref: "#/components/responses/Locked"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "499":
          $ref: "#/components/responses/ClientClosedRequest"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailableGeocoding"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

components:
  responses:
    MethodNotAllowed:
      description: |
        Method Not Allowed. Only the `GET` method is supported for this endpoint.

        Calling it with an HTTP method it doesn't support (for example `POST`, `PUT` or
        `DELETE`) results in HTTP 405.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            postNotAllowed:
              summary: POST used on a GET endpoint
              value:
                message: "Request method 'POST' is not supported"
            unsupportedMethod:
              summary: Unsupported HTTP method
              value:
                message: "Request method 'PUT' is not supported"

    MethodNotAllowedBulk:
      description: |
        Method Not Allowed. Only the `POST` method is supported for this bulk endpoint.

        Calling it with an HTTP method it doesn't support (for example `GET`, `PUT` or
        `DELETE`) results in HTTP 405.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            getNotAllowedForBulk:
              summary: GET used on bulk endpoint
              value:
                message: "Request method 'GET' is not supported"
            unsupportedMethod:
              summary: Unsupported HTTP method
              value:
                message: "Request method 'PUT' is not supported"

    MethodNotAllowedGetPost:
      description: |
        Method Not Allowed. Only the `GET` and `POST` methods are supported for this
        endpoint.

        Calling it with an HTTP method it doesn't support (for example `PUT` or
        `DELETE`) results in HTTP 405.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            unsupportedMethod:
              summary: Unsupported HTTP method
              value:
                message: "Request method 'PUT' is not supported"

    PayloadTooLarge:
      description: |
        Payload too large. Returned by the edge proxy (nginx) when raw POST body size
        exceeds configured limits before the request reaches the application.

        This status is based on payload byte size, not on the number of IP entries. It
        can occur even when `ips` contains only one very large value.

        If both conditions apply (oversized body and `ips` count > 50,000), HTTP 413 may
        be returned first because edge validation runs before application-level checks.
      content:
        text/html:
          schema:
            type: string
          example: |
            <html>
              <head>
                <title>413 Request Entity Too Large</title>
              </head>
              <body>
                <center><h1>413 Request Entity Too Large</h1></center>
                <hr><center>nginx/1.24.0 (Ubuntu)</center>
              </body>
            </html>

    UnsupportedMediaType:
      description: |
        Unsupported media type. The `Content-Type` header is not set to `application/json`.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Content-Type 'application/x-www-form-urlencoded' is not supported"
    Locked:
      description: |
        Locked. The provided IP address belongs to a bogon IP range or a private
        network and cannot be looked up.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "'10.0.0.1' is a bogon IP address."

    PaymentRequired:
      description: |
        Payment Required. Returned for a paid (non-Free) subscription whose active-until
        date has passed: one day after the active-until date for active or trialing
        subscriptions, and from the active-until date for past-due or deleted
        subscriptions. It is checked before any usage quota. Paused subscriptions and
        expired trials get HTTP 401 instead, and Free plan keys never get 402. Renew or
        upgrade the plan to continue using IPGeolocation API.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            expiredSubscription:
              summary: Subscription expired
              value:
                message: "Your subscription has expired at 2026-01-15 00:00. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"

    Forbidden:
      description: |
        Forbidden. The API key has an IP allow-list and the request comes from an IP address that is not on it.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Your IP address '203.0.113.10' is not allowed to use this API key. Please contact technical support for assistance at support@ipgeolocation.io"

    TooManyRequests:
      description: |
        Too Many Requests. Returned for one of the following reasons:

        - The API credit allowance has been reached for a Free subscription.
        - The API credit allowance has been reached for an active trial subscription (capped at 100,000 API credits).
        - The API credit allowance has been reached for a Paid subscription with surcharge usage disabled.
        - The API credit allowance has been reached for a Paid subscription with status 'past due' or 'deleted'.
        - The surcharge (overage) credit limit has been reached for the subscribed plan.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            usageLimitReached:
              summary: API credit limit reached
              value:
                message: "You have exceeded the limit of PLAN_REQUESTS_LIMIT requests per PLAN_INTERVAL for your subscribed 'PLAN_NAME' plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation API without interruption."
            trialLimitReached:
              summary: Trial credit cap (100,000) reached
              value:
                message: "You have exceeded the limit of 100000 requests per PLAN_INTERVAL for your subscribed 'PLAN_NAME' plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation API without interruption."
            surchargeLimitReached:
              summary: Surcharge usage limit reached
              value:
                message: "You have reached the surcharge amount limit of $SURCHARGE_AMOUNT_LIMIT on your subscribed 'PLAN_NAME' plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation API without interruption."

    ClientClosedRequest:
      description: |
        The client closed the connection before the server finished processing the
        request (logged by the edge proxy; the client receives no response). This
        usually happens when the client sets a very short request or connection
        timeout. Increase the client-side timeout.

    InternalServerError:
      description: |
        Internal Server Error. The server encountered an unexpected condition
        that prevented it from fulfilling the request. If the issue persists,
        contact support@ipgeolocation.io.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Something went wrong while processing your request. Please try again or contact technical support at support@ipgeolocation.io"
    BadGateway:
      description: |
        Bad Gateway. Returned by the edge proxy in front of the API, not by the API
        application, when it gets an invalid response from the API server. The
        response body is set by the proxy. This is usually temporary; retry the
        request.
    ServiceUnavailable:
      description: |
        Service Unavailable. Returned when the API cannot verify your API key (or request
        origin) because of a temporary internal error, for example when the billing
        service is unreachable and the key has not been verified recently. Keys that
        were verified recently keep working. Retry later; if it persists, contact
        support@ipgeolocation.io.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "We're unable to verify your API key (YOUR_API_KEY) due to an internal error. Please contact technical support for assistance at support@ipgeolocation.io"
    ServiceUnavailableGeocoding:
      description: |
        Service Unavailable. Returned when the API cannot verify your API key (or request
        origin) because of a temporary internal error, for example when the billing
        service is unreachable and the key has not been verified recently. Keys that
        were verified recently keep working. Retry later; if it persists, contact
        support@ipgeolocation.io.

        Also returned when a `location` (or `location_from`/`location_to`) value cannot
        be geocoded because the geocoding service is temporarily unavailable. Retry, or
        use coordinates.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          examples:
            apiKeyVerificationUnavailable:
              summary: API key could not be verified
              value:
                message: "We're unable to verify your API key (YOUR_API_KEY) due to an internal error. Please contact technical support for assistance at support@ipgeolocation.io"
            geocoderUnavailable:
              summary: Location could not be geocoded right now
              value:
                message: "We couldn't look up the location (London, UK) right now. Please try again shortly, or use the 'lat' and 'long' parameters instead."
    GatewayTimeout:
      description: |
        Gateway Timeout. Returned by the edge proxy in front of the API, not by the
        API application, when the API server does not respond in time. The response
        body is set by the proxy. Retry the request.
    HttpVersionNotSupported:
      description: |
        HTTP Version Not Supported. Returned by the edge proxy in front of the API,
        not by the API application, when the request uses an HTTP protocol version
        it does not support. The response body is set by the proxy.

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey
      description: |
        API key passed as the `apiKey` query parameter. Get yours from the
        [IPGeolocation dashboard](https://app.ipgeolocation.io/). For client-side
        usage, consider using Request Origin (CORS) authentication instead to
        avoid exposing your key.
  schemas:
    ErrorResponse:
      type: object
      description: |
        Returned for any non-200 response. Contains only a human-readable `message`.
        Message text can vary by status and condition; examples in this spec are
        representative, not exhaustive, and should not be treated as stable machine
        codes.
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable explanation of what went wrong. Use HTTP status for control flow.
          example: "Provided name, service or IP address '999.999.999.999' is not valid."
    GetIpResponse:
      type: object
      xml:
        name: LinkedHashMap
      description: |
        Response body for the Get IP endpoint. Contains only the caller's public
        IP address.
      required:
        - ip
      properties:
        ip:
          type: string
          description: |
            Public IP address of the client that called this endpoint. If called
            from a server, this is the server's IP. If called from client-side
            JavaScript, this is the visitor's public IP address.
          example: "8.8.8.8"
    BulkGeolocationRequest:
      type: object
      description: |
        Request body for the bulk geolocation lookup. Contains a single `ips` field
        with an array of IP addresses or domain names to look up.
      required:
        - ips
      properties:
        ips:
          type: array
          description: |
            Array of IPv4 addresses, IPv6 addresses, or domain names to look up.
            Must not be empty. Maximum 50,000 entries per request. Each entry is
            resolved independently, so you can mix IPv4, IPv6, and domains freely.
          minItems: 1
          maxItems: 50000
          items:
            type: string
          example:
            - "8.8.8.8"
            - "91.128.103.196"
            - "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
            - "ipgeolocation.io"

    BulkGeolocationResponseItem:
      description: |
        A single element in the bulk lookup response array. Each element is either a
        full geolocation object or an error object containing only `message`.
      discriminator:
        propertyName: type
        mapping:
          success: "#/components/schemas/BulkGeolocationSuccessItem"
          error: "#/components/schemas/BulkGeolocationErrorItem"
      oneOf:
        - $ref: "#/components/schemas/BulkGeolocationSuccessItem"
        - $ref: "#/components/schemas/BulkGeolocationErrorItem"


    BulkGeolocationSuccessItem:
      type: object
      required:
        - ip
      properties:
        ip:
          type: string
          description: |
            The resolved IP address for this bulk entry. For direct IPv4/IPv6 input,
            this matches the submitted value (normalized). For domain input, this is
            the resolved A/AAAA IP.
          example: "8.8.8.8"
        domain:
          type: string
          description: |
            Present only when the submitted `ips` entry was a domain name.
            The submitted domain, trimmed and without a leading `scheme://` (e.g. `https://`).
          example: "ipgeolocation.io"
        hostname:
          type: string
          description: |
            Reverse-DNS hostname for the IP. Only present when one of the hostname
            `include` options is used.
          example: "dns.google"
        location:
          $ref: "#/components/schemas/IPGeoLocation"
        country_metadata:
          $ref: "#/components/schemas/IPGeoCountryMetadata"
        network:
          $ref: "#/components/schemas/IPGeoNetwork"
        currency:
          $ref: "#/components/schemas/IPGeoCurrency"
        asn:
          $ref: "#/components/schemas/IPGeoAsn"
        company:
          $ref: "#/components/schemas/IPGeoCompany"
        security:
          $ref: "#/components/schemas/IPGeoSecurity"
        abuse:
          $ref: "#/components/schemas/IPGeoAbuse"
        time_zone:
          $ref: "#/components/schemas/IPGeoTimeZone"
        user_agent:
          $ref: "#/components/schemas/IPGeoUserAgent"

    BulkGeolocationErrorItem:
      type: object
      description: |
        Error object returned for an invalid entry in the bulk lookup request. Contains only
        a `message` field. Note: unlike success entries, error entries do NOT include the
        original `ip` field, so the only way to correlate errors to inputs is by array
        index. The response array preserves the same order as the request `ips` array.
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error for the specific bulk entry.
          example: "Provided name, service or IP address 'invalid-ip' is not valid."

    IpGeolocationResponse:
      type: object
      xml:
        name: LinkedHashMap
      description: |
        The top-level response object for a single IP lookup. Where fields and nested
        objects appear depends on your plan (free vs. paid) and the `include`, `fields`,
        and `excludes` parameters. The `ip` field, and `domain` on domain lookups, are
        always returned; `fields` and `excludes` cannot remove them.
      required:
        - ip
      properties:
        ip:
          type: string
          description: |
            The looked-up IP address. If a domain was queried, this is the resolved IP.
            If no `ip` parameter was sent, this is the caller's public IP.
          example: "91.128.103.196"
        domain:
          type: string
          description: |
            Present only when the `ip` query parameter contained a domain name. The
            submitted domain, trimmed and without a leading `scheme://` (e.g. `https://`).
          example: "ipgeolocation.io"
        hostname:
          type: string
          description: |
            Reverse-DNS hostname for the IP. Returned only when one of the hostname
            `include` options is used (`hostname`, `liveHostname`, or
            `hostnameFallbackLive`). If no hostname can be resolved, this field contains
            the IP address itself. The local hostname database (`include=hostname`) covers
            IPv4 only, so IPv6 lookups with `include=hostname` return the IP address.
          example: "host197.lightwavenetworks.com"
        location:
          $ref: "#/components/schemas/IPGeoLocation"
        country_metadata:
          $ref: "#/components/schemas/IPGeoCountryMetadata"
        network:
          $ref: "#/components/schemas/IPGeoNetwork"
        currency:
          $ref: "#/components/schemas/IPGeoCurrency"
        asn:
          $ref: "#/components/schemas/IPGeoAsn"
        company:
          $ref: "#/components/schemas/IPGeoCompany"
        security:
          $ref: "#/components/schemas/IPGeoSecurity"
        abuse:
          $ref: "#/components/schemas/IPGeoAbuse"
        time_zone:
          $ref: "#/components/schemas/IPGeoTimeZone"
        user_agent:
          $ref: "#/components/schemas/IPGeoUserAgent"

    IPGeoLocation:
      type: object
      description: Geographic location data for the IP address.
      properties:
        continent_code:
          type: string
          description: Two-letter continent code (e.g. `EU`, `NA`, `AS`).
          example: "EU"
        continent_name:
          type: string
          description: Full continent name.
          example: "Europe"
        country_code2:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: "SE"
        country_code3:
          type: string
          description: ISO 3166-1 alpha-3 country code.
          example: "SWE"
        country_name:
          type: string
          description: Common country name.
          example: "Sweden"
        country_name_official:
          type: string
          description: Official country name as recognized by the UN.
          example: "Kingdom of Sweden"
        country_capital:
          type: string
          description: Capital city of the country.
          example: "Stockholm"
        state_prov:
          type: string
          description: State, province, or top-level administrative region.
          example: "Stockholms län"
        state_code:
          type: string
          description: ISO 3166-2 state or province code.
          example: "SE-AB"
        district:
          type: string
          description: District, county, or second-level administrative division.
          example: "Stockholm"
        city:
          type: string
          description: City name.
          example: "Stockholm"
        locality:
          type: string
          description: |
            Locality or neighborhood. May be the same as `city`. Only present when
            `include=geo_accuracy` or `include=*` is used.
          example: "Stockholm"
        accuracy_radius:
          type: string
          description: |
            Estimated accuracy radius in kilometers around `latitude` and `longitude`.
            Only present when `include=geo_accuracy` or `include=*` is used.
          example: "4.395"
        confidence:
          type: string
          description: |
            Confidence level for the accuracy radius. Possible values: `high`, `medium`,
            `low`. Only present when `include=geo_accuracy` or `include=*` is used.
          enum:
            - high
            - medium
            - low
          example: "high"
        dma_code:
          type: string
          description: |
            Nielsen Designated Market Area code. Only populated for US-based IPs.
            Present when `include=dma_code` or `include=*` is used. Empty string for
            non-US IPs.
          example: "504"
        zipcode:
          type: string
          description: Postal or ZIP code.
          example: "164 40"
        latitude:
          type: string
          description: Latitude in decimal degrees (WGS 84).
          example: "59.40510"
        longitude:
          type: string
          description: Longitude in decimal degrees (WGS 84).
          example: "17.95510"
        is_eu:
          type: boolean
          description: Whether the country is a member of the European Union.
          example: true
        country_flag:
          type: string
          format: uri
          description: URL to a 64x64 PNG of the country flag.
          example: "https://ipgeolocation.io/static/flags/se_64.png"
        geoname_id:
          type: string
          description: GeoNames identifier for the location.
          example: "9972319"
        country_emoji:
          type: string
          description: Unicode flag emoji for the country.
          example: "\U0001F1F8\U0001F1EA"

    IPGeoCountryMetadata:
      type: object
      description: Telephone, TLD, and language information for the country.
      properties:
        calling_code:
          type: string
          description: International dialing code with leading `+`.
          example: "+46"
        tld:
          type: string
          description: Country-code top-level domain.
          example: ".se"
        languages:
          type: array
          description: |
            IETF language tags spoken in the country, ordered by prevalence.
          items:
            type: string
          example:
            - "sv-SE"
            - "se"
            - "sma"
            - "fi-SE"

    IPGeoNetwork:
      type: object
      description: |
        Network routing information for the IP. Included by default on paid plans.
        Not available on the free plan.
      properties:
        connection_type:
          type: string
          description: |
            Type of network connection for this IP. Known values: `DSL`, `Cable`,
            `Fiber`, `Mobile`, `Wireless`, `Dial-Up/ISDN`, `Satellite`. Empty string
            when the type cannot be determined.
          example: ""
        route:
          type: string
          description: BGP route prefix in CIDR notation.
          example: "91.128.0.0/14"
        is_anycast:
          type: boolean
          description: Whether the IP is part of an anycast network.
          example: false
        is_cdn:
          type: boolean
          description: |
            Whether the IP is part of a Content Delivery Network (CDN) or cloud
            provider network.
          example: false
        cdn_provider_name:
          type: string
          description: |
            Name of the CDN provider when `is_cdn` is `true` (e.g. `Cloudflare`).
            Empty string otherwise.
          example: ""
    IPGeoCurrency:
      type: object
      description: Local currency of the country where the IP is located.
      properties:
        code:
          type: string
          description: ISO 4217 currency code.
          example: "SEK"
        name:
          type: string
          description: Currency name.
          example: "Swedish Krona"
        symbol:
          type: string
          description: Currency symbol.
          example: "kr"

    IPGeoAsn:
      type: object
      description: |
        Autonomous System Number details for the IP. Free plans receive `as_number`,
        `organization`, and `country` only. Paid plans also receive `type`, `domain`,
        `date_allocated`, and `rir`.
      properties:
        as_number:
          type: string
          description: AS number prefixed with `AS` (e.g. `AS1257`).
          example: "AS1257"
        organization:
          type: string
          description: Name of the organization that owns the ASN.
          example: "Tele2 Sverige AB"
        country:
          type: string
          description: ISO 3166-1 alpha-2 country where the ASN is registered.
          example: "SE"
        type:
          type: string
          description: |
            Organization type. Values: `ISP`, `HOSTING`, `BUSINESS`, `EDUCATION`,
            `GOVERNMENT`. Paid plans only.
          example: "ISP"
        domain:
          type: string
          description: Primary domain of the ASN holder. Paid plans only.
          example: "tele2.com"
        date_allocated:
          type: string
          description: |
            Date when the ASN was allocated, in `YYYY-MM-DD` format (e.g.
            `2024-12-13`). Paid plans only.
          example: "2024-12-13"
        rir:
          type: string
          description: |
            Regional Internet Registry (RIR) that allocated the ASN. Possible values include `RIPE`, `ARIN`, `APNIC`, `LACNIC`, `AFRINIC`, etc.
          example: "RIPE"

    IPGeoCompany:
      type: object
      description: |
        Company or organization operating the IP range. Included by default on paid
        plans. Not available on the free plan.
      properties:
        name:
          type: string
          description: Company or organization name.
          example: "Tele2 Sverige AB"
        type:
          type: string
          description: |
            Company category. Documented values: `ISP`, `HOSTING`, `BUSINESS`,
            `EDUCATION`, `GOVERNMENT`. All uppercase, consistent with `asn.type`.
            May be an empty string when the company type cannot be determined.
          example: "ISP"
        domain:
          type: string
          description: Primary domain of the company.
          example: "tele2.com"

    IPGeoSecurity:
      type: object
      description: |
        Threat intelligence and anonymization signals for the IP. Only returned when
        `include=security` or `include=*` is used. Costs 2 additional credits.
      properties:
        threat_score:
          type: number
          description: |
            Overall threat score from 0 (clean) to 100 (high risk). Aggregated from
            all the individual signals below.
          minimum: 0
          maximum: 100
          example: 80
        is_tor:
          type: boolean
          description: Whether the IP is a known Tor exit node.
          example: false
        is_proxy:
          type: boolean
          description: Whether the IP belongs to a known proxy service.
          example: true
        proxy_provider_names:
          type: array
          description: Names of proxy providers associated with this IP, if any.
          items:
            type: string
          example:
            - "Zyte Proxy"
        proxy_confidence_score:
          type: number
          description: |
            Confidence that this IP is a proxy, from 0 to 100. Only meaningful when
            `is_proxy` is `true`.
          minimum: 0
          maximum: 100
          example: 90
        proxy_last_seen:
          type: string
          description: |
            Date when this IP was last observed acting as a proxy, in `YYYY-MM-DD`
            format. Empty string if never seen.
          example: "2025-12-12"
        proxy_days_seen_30d:
          type: integer
          description: Number of days in the last 30 days this IP was observed acting as a proxy.
          example: 4
        proxy_days_seen_7d:
          type: integer
          description: Number of days in the last 7 days this IP was observed acting as a proxy.
          example: 1
        proxy_provider_count_30d:
          type: integer
          description: Number of distinct proxy providers associated with this IP in the last 30 days.
          example: 1
        is_residential_proxy:
          type: boolean
          description: Whether the IP is a known residential proxy.
          example: true
        is_vpn:
          type: boolean
          description: Whether the IP belongs to a known VPN provider.
          example: true
        vpn_provider_names:
          type: array
          description: Names of VPN providers associated with this IP, if any.
          items:
            type: string
          example:
            - "Nord VPN"
        vpn_confidence_score:
          type: number
          description: |
            Confidence that this IP is a VPN endpoint, from 0 to 100. Only meaningful
            when `is_vpn` is `true`.
          minimum: 0
          maximum: 100
          example: 90
        vpn_last_seen:
          type: string
          description: |
            Date when this IP was last observed as a VPN endpoint, in `YYYY-MM-DD`
            format. Empty string if never seen.
          example: "2026-01-19"
        is_relay:
          type: boolean
          description: Whether the IP is part of a known relay network (e.g. iCloud Private Relay).
          example: false
        relay_provider_name:
          type: string
          description: Name of the relay provider, if any. Empty string if not a relay.
          example: ""
        is_anonymous:
          type: boolean
          description: |
            Whether the IP is associated with any anonymization method (VPN, proxy,
            Tor, or relay).
          example: true
        is_known_attacker:
          type: boolean
          description: Whether the IP has been flagged in known attacker or threat feeds.
          example: true
        is_bot:
          type: boolean
          description: Whether the IP is associated with known bot activity.
          example: false
        bot_confidence_score:
          type: number
          description: |
            Confidence that this IP is associated with bot activity, from 0 to 100.
            Only populated when `is_bot` is `true`; otherwise `0`.
          minimum: 0
          maximum: 100
          example: 0
        bot_operator_name:
          type: string
          description: |
            Organization operating the bot. Typically only populated for known good
            bots (see `is_known_good_bot`). Empty string otherwise.
          example: ""
        bot_type:
          type: string
          description: |
            Type of bot activity detected, when available (e.g. `search_engine`,
            `ai_crawler`, `scraper`, `exploit`). Empty string if unknown.
          example: ""
          externalDocs:
            description: bot_type values reference
            url: "https://ipgeolocation.io/documentation/ip-security-api.html#bot-type-values"
        is_known_good_bot:
          type: boolean
          description: |
            Whether the bot is declared and verifiable, such as a search engine
            crawler, uptime monitor, or security scanner.
          example: false
        bot_last_seen:
          type: string
          description: |
            Date when this IP was last observed engaging in bot activity, in
            `YYYY-MM-DD` format. Empty string if never seen.
          example: ""
        is_spam:
          type: boolean
          description: Whether the IP is listed in spam databases.
          example: false
        is_cloud_provider:
          type: boolean
          description: Whether the IP belongs to a cloud hosting or data center provider.
          example: true
        cloud_provider_name:
          type: string
          description: Name of the cloud provider, if applicable. Empty string otherwise.
          example: "Packethub S.A."
        is_corporate_gateway:
          type: boolean
          description: |
            Whether the IP is an egress address of a secure web gateway (SWG),
            security service edge (SSE), or secure access service edge (SASE) product.
          example: false
        corporate_gateway_type:
          type: string
          description: |
            Type of corporate gateway service, when available (`secure_web_gateway`
            or `browser_isolation`). Empty string if unknown.
          example: ""
          externalDocs:
            description: corporate_gateway_type values reference
            url: "https://ipgeolocation.io/documentation/ip-security-api.html#corporate-gateway-type-values"
        corporate_gateway_provider_name:
          type: string
          description: |
            Name of the corporate gateway provider, when available. Empty string
            otherwise.
          example: ""

    IPGeoAbuse:
      type: object
      description: |
        Abuse contact information for the network that owns this IP. Only returned when
        `include=abuse` or `include=*` is used. Costs 1 additional credit.
      properties:
        route:
          type: string
          description: BGP route prefix this abuse contact is responsible for, in CIDR notation.
          example: "91.128.0.0/14"
        country:
          type: string
          description: ISO 3166-1 alpha-2 country of the abuse contact. May be empty.
          example: "SE"
        name:
          type: string
          description: Name of the abuse contact person or team.
          example: "Swipnet Staff"
        organization:
          type: string
          description: Organization name of the abuse contact. May be empty.
          example: ""
        kind:
          type: string
          description: |
            Contact type from registry data. Values include `group`, `individual`.
          example: "group"
        address:
          type: string
          description: Postal address of the abuse contact. Returned as a plain comma-separated string.
          example: "Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN"
        emails:
          type: array
          description: Email addresses for reporting abuse.
          items:
            type: string
            format: email
          example:
            - "abuse@tele2.com"
        phone_numbers:
          type: array
          description: Phone numbers for the abuse contact.
          items:
            type: string
          example:
            - "+46 8 5626 42 10"

    IPGeoTimeZone:
      type: object
      description: Timezone information for the geographic location of the IP.
      properties:
        name:
          type: string
          description: IANA timezone identifier.
          example: "Europe/Stockholm"
        offset:
          type: number
          format: float
          description: UTC offset in hours (without DST).
          example: 1
        offset_with_dst:
          type: number
          format: float
          description: |
            Current UTC offset in hours, accounting for DST if active. Same as
            `offset` when DST is not in effect.
          example: 1
        current_time:
          type: string
          description: |
            Current local date and time at the IP's location, in `yyyy-MM-dd HH:mm:ss.SSSZ`
            format, e.g. `2026-02-13 09:19:24.410+0100`.
          example: "2026-02-13 09:19:24.410+0100"
        current_time_unix:
          type: number
          format: float
          description: Current time as a Unix timestamp with millisecond precision.
          example: 1770970764.41
        current_tz_abbreviation:
          type: string
          description: |
            Abbreviation of the timezone currently in effect (may be standard or DST).
          example: "CET"
        current_tz_full_name:
          type: string
          description: Full name of the timezone currently in effect.
          example: "Central European Standard Time"
        standard_tz_abbreviation:
          type: string
          description: Abbreviation of the standard (non-DST) timezone.
          example: "CET"
        standard_tz_full_name:
          type: string
          description: Full name of the standard (non-DST) timezone.
          example: "Central European Standard Time"
        is_dst:
          type: boolean
          description: Whether Daylight Saving Time is currently active.
          example: false
        dst_savings:
          type: number
          format: float
          description: |
            DST offset in hours applied on top of the standard offset when DST is
            active. `0` means no DST shift (either DST is not active or does not exist).
          example: 0
        dst_exists:
          type: boolean
          description: Whether this timezone observes Daylight Saving Time at all.
          example: true
        dst_tz_abbreviation:
          type: string
          description: |
            Abbreviation of the DST timezone. Empty string if DST is not observed.
          example: "CEST"
        dst_tz_full_name:
          type: string
          description: |
            Full name of the DST timezone. Empty string if DST is not observed.
          example: "Central European Summer Time"
        dst_start:
          description: |
            Start DST transition details. When `dst_exists` is `false`, this is
            returned as an empty object with no properties.
          anyOf:
            - $ref: "#/components/schemas/IPGeoDstTransition"
            - type: object
              maxProperties: 0
        dst_end:
          description: |
            End DST transition details. When `dst_exists` is `false`, this is
            returned as an empty object with no properties.
          anyOf:
            - $ref: "#/components/schemas/IPGeoDstTransition"
            - type: object
              maxProperties: 0

    IPGeoDstTransition:
      type: object
      description: |
        Details about a DST transition (start or end). Only present when `dst_exists`
        is `true`. When `dst_exists` is `false`, `dst_start` and `dst_end` are
        returned as empty objects with no properties.
        `dst_start` and `dst_end` describe the current DST period while DST is
        in effect, otherwise the next one.
      properties:
        utc_time:
          type: string
          description: UTC time of the transition, formatted as `YYYY-MM-DD TIME HH:mm`.
          example: "2026-03-29 TIME 01:00"
        duration:
          type: string
          description: |
            Clock shift direction and amount (e.g. `+1.00H` for spring forward,
            `-1.00H` for fall back).
          example: "+1.00H"
        gap:
          type: boolean
          description: |
            Whether this transition creates a gap in local time (clocks jump forward).
            `true` for DST start, `false` for DST end.
          example: true
        date_time_after:
          type: string
          description: Local time immediately after the transition.
          example: "2026-03-29 TIME 03:00"
        date_time_before:
          type: string
          description: Local time immediately before the transition.
          example: "2026-03-29 TIME 02:00"
        overlap:
          type: boolean
          description: |
            Whether this transition creates an overlap in local time (clocks fall back,
            so the same local time occurs twice). `true` for DST end, `false` for DST
            start.
          example: false

    IPGeoUserAgent:
      type: object
      description: |
        Parsed User-Agent information. Only returned when `include=user_agent` or
        `include=*` is used. The API parses the `User-Agent` header from the request.
        For server-side usage, forward your visitor's User-Agent string in the header.
      properties:
        user_agent_string:
          type: string
          description: The raw User-Agent string that was parsed.
          example: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0"
        name:
          type: string
          description: Detected browser or client name.
          example: "Edge"
        type:
          type: string
          description: |
            Client type classification. Common values: `Browser`, `Robot`,
            `Mobile Browser`, `Library`.
          example: "Browser"
        version:
          type: string
          description: Full version string of the detected client.
          example: "143"
        version_major:
          type: string
          description: Major version number of the detected client.
          example: "143"
        device:
          $ref: "#/components/schemas/IPGeoUserAgentDevice"
        engine:
          $ref: "#/components/schemas/IPGeoUserAgentEngine"
        operating_system:
          $ref: "#/components/schemas/IPGeoUserAgentOperatingSystem"

    IPGeoUserAgentDevice:
      type: object
      description: Device information extracted from the User-Agent string.
      properties:
        name:
          type: string
          description: Device name or model.
          example: "Linux Desktop"
        type:
          type: string
          description: |
            Device type. Common values: `Desktop`, `Smartphone`, `Tablet`, `Robot`,
            `Smart TV`.
          example: "Desktop"
        brand:
          type: string
          description: Device manufacturer or brand. `Unknown` if not detectable.
          example: "Unknown"
        cpu:
          type: string
          description: CPU architecture if detectable (e.g. `Intel x86_64`, `ARM`). `Unknown` otherwise.
          example: "Intel x86_64"

    IPGeoUserAgentEngine:
      type: object
      description: Rendering engine information extracted from the User-Agent string.
      properties:
        name:
          type: string
          description: Engine name (e.g. `Blink`, `Gecko`, `WebKit`).
          example: "Blink"
        type:
          type: string
          description: Engine classification. Typically matches the client type.
          example: "Browser"
        version:
          type: string
          description: Full version of the rendering engine.
          example: "143"
        version_major:
          type: string
          description: Major version of the rendering engine.
          example: "143"
    IPGeoUserAgentOperatingSystem:
      type: object
      description: Operating system information extracted from the User-Agent string.
      properties:
        name:
          type: string
          description: OS name (e.g. `Windows`, `macOS`, `Linux`, `Android`, `iOS`, `Cloud`).
          example: "Linux"
        type:
          type: string
          description: |
            OS type. Common values: `Desktop`, `Mobile`, `Tablet`, `Cloud`.
          example: "Desktop"
        version:
          type: string
          description: OS version. `??` when the version cannot be determined.
          example: "??"
        version_major:
          type: string
          description: OS major version. `??` when the version cannot be determined.
          example: "??"
        build:
          type: string
          description: OS build number. `??` when the build cannot be determined.
          example: "??"

    BulkSecurityRequest:
      type: object
      description: |
        Request body for the bulk security lookup. Contains a single `ips` field
        with an array of IP addresses to look up.
      required:
        - ips
      properties:
        ips:
          type: array
          description: |
            Array of IPv4 addresses or IPv6 addresses to look up.
            Must not be empty. Maximum 50,000 entries per request. Each entry is
            resolved independently, so you can mix IPv4 and IPv6 freely.
          minItems: 1
          maxItems: 50000
          items:
            type: string
          example:
            - "8.8.8.8"
            - "91.128.103.196"
            - "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"

    BulkSecurityResponseItem:
      description: |
        A single element in the bulk lookup response array. Each element is either a
        full security object or an error object containing only `message`.
      oneOf:
        - $ref: "#/components/schemas/BulkSecuritySuccessItem"
        - $ref: "#/components/schemas/BulkSecurityErrorItem"


    BulkSecuritySuccessItem:
      type: object
      required:
        - ip
        - security
      properties:
        ip:
          type: string
          description: IP address for this lookup result.
          example: "2.56.188.34"

        security:
          $ref: "#/components/schemas/Security"

    BulkSecurityErrorItem:
      type: object
      description: |
        Error object returned for an invalid entry in the bulk lookup request. Contains only
        a `message` field. Note: unlike success entries, error entries do NOT include the
        original `ip` field, so the only way to correlate errors to inputs is by array
        index. The response array preserves the same order as the request `ips` array.
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error for the specific bulk entry.
          example: "Provided IP address 'invalid-ip' is not valid."


    IpSecurityResponse:
      type: object
      xml:
        name: LinkedHashMap
      required:
        - ip
      properties:
        ip:
          type: string
          description: IP address used for the lookup.
          example: "2.56.188.34"

        security:
          $ref: "#/components/schemas/Security"

    Security:
      type: object
      description: |
        Threat intelligence and anonymization signals for the IP. Costs 2 credits.
      properties:
        threat_score:
          type: number
          description: |
            Overall threat score from 0 (clean) to 100 (high risk). Aggregated from
            all the individual signals below.
          minimum: 0
          maximum: 100
          example: 80
        is_tor:
          type: boolean
          description: Whether the IP is a known Tor exit node.
          example: false
        is_proxy:
          type: boolean
          description: Whether the IP belongs to a known proxy service.
          example: true
        proxy_provider_names:
          type: array
          description: Names of proxy providers associated with this IP, if any.
          items:
            type: string
          example:
            - "Zyte Proxy"
        proxy_confidence_score:
          type: number
          description: |
            Confidence that this IP is a proxy, from 0 to 100. Only meaningful when
            `is_proxy` is `true`.
          minimum: 0
          maximum: 100
          example: 90
        proxy_last_seen:
          type: string
          description: |
            Date when this IP was last observed acting as a proxy, in `YYYY-MM-DD`
            format. Empty string if never seen.
          example: "2025-12-12"
        proxy_days_seen_30d:
          type: integer
          description: Number of days in the last 30 days this IP was observed acting as a proxy.
          example: 4
        proxy_days_seen_7d:
          type: integer
          description: Number of days in the last 7 days this IP was observed acting as a proxy.
          example: 1
        proxy_provider_count_30d:
          type: integer
          description: Number of distinct proxy providers associated with this IP in the last 30 days.
          example: 1
        is_residential_proxy:
          type: boolean
          description: Whether the IP is a known residential proxy.
          example: true
        is_vpn:
          type: boolean
          description: Whether the IP belongs to a known VPN provider.
          example: true
        vpn_provider_names:
          type: array
          description: Names of VPN providers associated with this IP, if any.
          items:
            type: string
          example:
            - "Nord VPN"
        vpn_confidence_score:
          type: number
          description: |
            Confidence that this IP is a VPN endpoint, from 0 to 100. Only meaningful
            when `is_vpn` is `true`.
          minimum: 0
          maximum: 100
          example: 90
        vpn_last_seen:
          type: string
          description: |
            Date when this IP was last observed as a VPN endpoint, in `YYYY-MM-DD`
            format. Empty string if never seen.
          example: "2026-01-19"
        is_relay:
          type: boolean
          description: Whether the IP is part of a known relay network (e.g. iCloud Private Relay).
          example: false
        relay_provider_name:
          type: string
          description: Name of the relay provider, if any. Empty string if not a relay.
          example: ""
        is_anonymous:
          type: boolean
          description: |
            Whether the IP is associated with any anonymization method (VPN, proxy,
            Tor, or relay).
          example: true
        is_known_attacker:
          type: boolean
          description: Whether the IP has been flagged in known attacker or threat feeds.
          example: true
        is_bot:
          type: boolean
          description: Whether the IP is associated with known bot activity.
          example: false
        bot_confidence_score:
          type: number
          description: |
            Confidence that this IP is associated with bot activity, from 0 to 100.
            Only populated when `is_bot` is `true`; otherwise `0`.
          minimum: 0
          maximum: 100
          example: 0
        bot_operator_name:
          type: string
          description: |
            Organization operating the bot. Typically only populated for known good
            bots (see `is_known_good_bot`). Empty string otherwise.
          example: ""
        bot_type:
          type: string
          description: |
            Type of bot activity detected, when available (e.g. `search_engine`,
            `ai_crawler`, `scraper`, `exploit`). Empty string if unknown.
          example: ""
          externalDocs:
            description: bot_type values reference
            url: "https://ipgeolocation.io/documentation/ip-security-api.html#bot-type-values"
        is_known_good_bot:
          type: boolean
          description: |
            Whether the bot is declared and verifiable, such as a search engine
            crawler, uptime monitor, or security scanner.
          example: false
        bot_last_seen:
          type: string
          description: |
            Date when this IP was last observed engaging in bot activity, in
            `YYYY-MM-DD` format. Empty string if never seen.
          example: ""
        is_spam:
          type: boolean
          description: Whether the IP is listed in spam databases.
          example: false
        is_cloud_provider:
          type: boolean
          description: Whether the IP belongs to a cloud hosting or data center provider.
          example: true
        cloud_provider_name:
          type: string
          description: Name of the cloud provider, if applicable. Empty string otherwise.
          example: "Packethub S.A."
        is_corporate_gateway:
          type: boolean
          description: |
            Whether the IP is an egress address of a secure web gateway (SWG),
            security service edge (SSE), or secure access service edge (SASE) product.
          example: false
        corporate_gateway_type:
          type: string
          description: |
            Type of corporate gateway service, when available (`secure_web_gateway`
            or `browser_isolation`). Empty string if unknown.
          example: ""
          externalDocs:
            description: corporate_gateway_type values reference
            url: "https://ipgeolocation.io/documentation/ip-security-api.html#corporate-gateway-type-values"
        corporate_gateway_provider_name:
          type: string
          description: |
            Name of the corporate gateway provider, when available. Empty string
            otherwise.
          example: ""

    ASNLookupResponse:
      type: object
      xml:
        name: LinkedHashMap
      description: |
        Response returned by the ASN Lookup API.

        Contains the queried IP address (when an IP lookup is performed) and
        the ASN information associated with the network responsible for routing
        that IP address.

        When the lookup is performed using the `asn` parameter, the `ip` field
        is not included in the response.
      properties:
        ip:
          type: string
          description: |
            The IP address for which ASN details are returned. This field appears
            only when the lookup is performed using an IP address.
          example: "49.12.0.0"
        asn:
          $ref: "#/components/schemas/ASN"

    ASN:
      type: object
      description: |
        ASN information describing the Autonomous System responsible for routing
        the queried IP address or the specified ASN. Costs 1 credit.
      properties:
        as_number:
          type: string
          description: Complete Autonomous System Number that was looked up.
          example: "AS24940"

        organization:
          type: string
          description: Name of the organization to which the ASN is assigned.
          example: "Hetzner Online GmbH"

        country:
          type: string
          description: ISO 3166-1 alpha-2 country code where the ASN is registered.
          example: "DE"

        asn_name:
          type: string
          description: Official ASN handle.
          example: "HETZNER-AS"

        type:
          type: string
          description: |
            ASN category. Possible values include `ISP`, `HOSTING`, `BUSINESS`,
            `EDUCATION`, or `GOVERNMENT` when available.
          example: "HOSTING"

        domain:
          type: string
          description: Domain associated with the ASN.
          example: "hetzner.com"

        date_allocated:
          type: string
          description: Date when the ASN was originally allocated.
          example: "2002-06-03"

        rir:
          type: string
          description: |
            Regional Internet Registry that allocated the ASN.
            Examples include `RIPE`, `ARIN`, `APNIC`, `LACNIC`, `AFRINIC`, etc.
          example: "RIPE"

        allocation_status:
          type: string
          description: Current allocation status of the ASN.
          example: "ASSIGNED"

        num_of_ipv4_routes:
          type: string
          description: Number of IPv4 prefixes announced by this ASN.
          example: "84"

        num_of_ipv6_routes:
          type: string
          description: Number of IPv6 prefixes announced by this ASN.
          example: "6"

        peers:
          type: array
          description: Directly connected peer ASNs.
          items:
            $ref: "#/components/schemas/ASNConnection"

        downstreams:
          type: array
          description: Downstream (customer) ASNs connected to this ASN.
          items:
            $ref: "#/components/schemas/ASNConnection"

        upstreams:
          type: array
          description: Upstream provider ASNs used for internet connectivity.
          items:
            $ref: "#/components/schemas/ASNConnection"

        routes:
          type: array
          description: IPv4 and IPv6 prefixes announced by this ASN.
          items:
            type: string
          example:
            - "192.76.177.0/24"
            - "2607:f600::/32"

        whois_response:
          type: string
          description: Raw WHOIS registry record text returned for the ASN.
          example: "ASNumber: 24940\nOrgName: Hetzner Online GmbH\nCountry: DE"

    ASNConnection:
      type: object
      description: |
        Represents a connected Autonomous System such as a peer,
        upstream provider, or downstream customer.
      properties:
        as_number:
          type: string
          description: Autonomous System Number of the connected network.
          example: "AS3356"

        description:
          type: string
          description: Name or description of the connected network operator.
          example: "Level 3 Parent, LLC"

        country:
          type: string
          description: Country code of the connected ASN.
          example: "US"

    BulkAbuseRequest:
      type: object
      description: |
        Request body for the bulk abuse contact lookup. Contains a single `ips` field
        with an array of IP addresses to look up.
      required:
        - ips
      properties:
        ips:
          type: array
          description: |
            Array of IPv4 addresses or IPv6 addresses to look up.
            Must not be empty. Maximum 50,000 entries per request. Each entry is
            resolved independently, so you can mix IPv4 and IPv6 freely.
          minItems: 1
          maxItems: 50000
          items:
            type: string
          example:
            - "1.0.0.0"
            - "91.128.103.196"
            - "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"

    BulkAbuseResponseItem:
      description: |
        A single element in the bulk lookup response array. Each element is either a
        full abuse contact lookup object or an error object containing only `message`.
      oneOf:
        - $ref: "#/components/schemas/BulkAbuseSuccessItem"
        - $ref: "#/components/schemas/BulkAbuseErrorItem"

    BulkAbuseSuccessItem:
      type: object
      required:
        - ip
        - abuse
      properties:
        ip:
          type: string
          description: IP address for this lookup result.
          example: "1.0.0.0"
        abuse:
          $ref: "#/components/schemas/Abuse"

    BulkAbuseErrorItem:
      type: object
      description: |
        Error object returned for an entry in the bulk lookup request that has no abuse
        contact data (invalid, empty, null, private or bogon IP, or an IP with no abuse
        contact in the database). Contains only a `message` field. Note: unlike success
        entries, error entries do NOT include the original `ip` field, so the only way to
        correlate errors to inputs is by array index. The response array preserves the
        same order as the request `ips` array.
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error for the specific bulk entry.
          example: "Provided IP address 'invalid-ip' is not valid."

    AbuseLookupResponse:
      type: object
      xml:
        name: LinkedHashMap
      description: |
        Response returned by the IP Abuse Contact API.

        Contains the queried IP address and the abuse contact information
        associated with the network responsible for that IP.

        The `ip` field is always present. The `abuse` object may be partially
        populated depending on available registry data and field filtering.
      required:
        - ip
        - abuse
      properties:
        ip:
          type: string
          description: |
            The IP address for which abuse contact details are returned.
          example: "1.0.0.0"
        abuse:
          $ref: "#/components/schemas/Abuse"

    Abuse:
      type: object
      description: |
        Abuse contact information for the network that owns this IP. Costs 1 credit.
      properties:
        route:
          type: string
          description: BGP route prefix this abuse contact is responsible for, in CIDR notation.
          example: "91.128.0.0/14"
        country:
          type: string
          description: ISO 3166-1 alpha-2 country of the abuse contact. May be empty.
          example: "SE"
        name:
          type: string
          description: Name of the abuse contact person or team.
          example: "Swipnet Staff"
        organization:
          type: string
          description: Organization name of the abuse contact. May be empty.
          example: ""
        kind:
          type: string
          description: |
            Contact type from registry data. Values include `group`, `individual`.
          example: "group"
        address:
          type: string
          description: Postal address of the abuse contact. Returned as a plain comma-separated string.
          example: "Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN"
        emails:
          type: array
          description: Email addresses for reporting abuse.
          items:
            type: string
            format: email
          example:
            - "abuse@tele2.com"
        phone_numbers:
          type: array
          description: Phone numbers for the abuse contact.
          items:
            type: string
          example:
            - "+46 8 5626 42 10"

    TimezoneLookupResponse:
      type: object
      xml:
        name: LinkedHashMap
      description: |
        Response returned by the Timezone Lookup API.

        Contains timezone information for the requested identifier such as a
        timezone name, IP address, geographic coordinates, location address,
        airport code (IATA/ICAO), or UN/LOCODE.

        Depending on the lookup method used, additional contextual objects may
        be returned:

        - `ip` appears when the lookup is performed using an IP address or when
          no parameters are provided (caller IP lookup).
        - `location` appears when the lookup is performed using an IP address
          or location address.
        - `airport_details` appears when the lookup is performed using
          `iata_code` or `icao_code`.
        - `lo_code_details` appears when the lookup is performed using
          `lo_code`.

        The `time_zone` object is always present in the response.
      properties:
        ip:
          type: string
          description: |
            The IP address used to determine the timezone. This field appears
            only when the lookup is performed using an IP address or when the
            API resolves the caller's IP automatically.
          example: "8.8.8.8"

        location:
          description: |
            Geolocation details for the resolved location.

            When the lookup is performed using the `ip` parameter (or the
            caller's IP is resolved automatically), this is the IP-based
            shape (`TimezoneLocationFromIp`). When the lookup is performed
            using the `location` parameter, this is the smaller,
            geocoded-address shape (`TimezoneLocationFromName`).
          anyOf:
            - $ref: "#/components/schemas/TimezoneLocationFromIp"
            - $ref: "#/components/schemas/TimezoneLocationFromName"

        airport_details:
          $ref: "#/components/schemas/TimezoneAirportDetails"

        lo_code_details:
          $ref: "#/components/schemas/TimezoneLocodeDetails"

        time_zone:
          $ref: "#/components/schemas/Timezone"


    TimeConversionResponse:
      type: object
      xml:
        name: LinkedHashMap
      description: |
        Response returned by the Timezone Conversion API.

        Contains the original timestamp, the converted timestamp in the
        destination timezone, and the time difference between the two
        locations or timezones.

        The conversion can be performed using timezone names, geographic
        coordinates, location addresses, airport codes (IATA/ICAO),
        or UN/LOCODE identifiers.
      properties:
        original_time:
          type: string
          description: |
            The original timestamp before conversion. If the `time`
            parameter is omitted, this value represents the current
            time at the source location.
          example: "2024-12-08 11:00:00"

        converted_time:
          type: string
          description: |
            The converted timestamp in the destination timezone.
          example: "2024-12-08 18:30:00"

        diff_hour:
          type: number
          format: float
          description: |
            Absolute time difference between the source and destination timezones, in
            hours (always zero or positive). Compare `converted_time` with
            `original_time` to see which zone is ahead.
          example: 7.5

        diff_min:
          type: number
          description: |
            Absolute time difference between the source and destination timezones, in
            minutes (always zero or positive).
          example: 450


    Timezone:
      type: object
      description: |
        Detailed timezone information for the requested location or identifier.

        Contains timezone metadata such as UTC offset, daylight saving time (DST)
        status, formatted timestamps, and DST transition information.
      properties:
        name:
          type: string
          description: IANA timezone identifier for the location.
          example: "America/Los_Angeles"

        offset:
          type: number
          format: float
          description: Standard timezone offset from UTC in hours.
          example: -8

        offset_with_dst:
          type: number
          format: float
          description: Timezone offset from UTC including daylight saving time.
          example: -7

        date:
          type: string
          description: Current date in `YYYY-MM-DD` format.
          example: "2025-04-24"

        date_time:
          type: string
          description: Current date and time in `YYYY-MM-DD HH:mm:ss` format.
          example: "2025-04-24 11:30:12"

        date_time_txt:
          type: string
          description: Human-readable date and time string.
          example: "Thursday, April 24, 2025 11:30:12"

        date_time_wti:
          type: string
          description: Date and time with timezone information.
          example: "Thu, 24 Apr 2025 11:30:12 -0700"

        date_time_ymd:
          type: string
          description: ISO-8601 formatted date and time with timezone offset.
          example: "2025-04-24T11:30:12-0700"

        current_time:
          type: string
          description: |
            Current local date and time in `yyyy-MM-dd HH:mm:ss.SSSZ` format, e.g.
            `2026-03-07 10:37:39.744+0100`.
          example: "2026-02-13 09:19:24.410+0100"

        current_time_unix:
          type: number
          format: float
          description: Unix timestamp representing the current date and time.
          example: 1745519412.353

        time_24:
          type: string
          description: Current local time in 24-hour format.
          example: "11:30:12"

        time_12:
          type: string
          description: Current local time in 12-hour format.
          example: "11:30:12 AM"

        week:
          type: number
          description: Week number of the current year.
          example: 17

        month:
          type: number
          description: Current month number.
          example: 4

        year:
          type: number
          description: Four-digit year.
          example: 2025

        year_abbr:
          type: string
          description: Two-digit abbreviated year.
          example: "25"

        current_tz_abbreviation:
          type: string
          description: Abbreviation of the timezone currently in effect.
          example: "AEST"

        current_tz_full_name:
          type: string
          description: Full name of the timezone currently in effect.
          example: "Australian Eastern Standard Time"

        standard_tz_abbreviation:
          type: string
          description: Standard (non-DST) timezone abbreviation.
          example: "AEST"

        standard_tz_full_name:
          type: string
          description: Full name of the standard timezone.
          example: "Australian Eastern Standard Time"

        is_dst:
          type: boolean
          description: Indicates whether daylight saving time is currently active.

        dst_savings:
          type: number
          format: float
          description: |
            Daylight saving offset currently in effect, in hours (for example `1` or
            `0.5`). It is `0` when DST is not active right now, even if the zone observes
            DST.

        dst_exists:
          type: boolean
          description: Indicates whether the region observes daylight saving time.

        dst_tz_abbreviation:
          type: string
          description: Abbreviation used during daylight saving time.
          example: "PDT"

        dst_tz_full_name:
          type: string
          description: Full name used during daylight saving time.
          example: "Pacific Daylight Time"

        dst_start:
          $ref: "#/components/schemas/TimezoneDSTTransition"

        dst_end:
          $ref: "#/components/schemas/TimezoneDSTTransition"


    TimezoneDSTTransition:
      type: object
      description: |
        A daylight saving time transition. While DST is in effect, `dst_start` and
        `dst_end` describe the current DST period; otherwise they describe the next DST
        period. For time zones that do not observe DST, both are returned as empty
        objects (`{}`).
      properties:
        utc_time:
          type: string
          description: UTC timestamp when the DST transition occurs.
          example: "2026-03-29 TIME 01:00"

        duration:
          type: string
          description: Time change applied during the transition.
          example: "+1.00H"

        gap:
          type: boolean
          description: Indicates whether an hour is skipped during the transition.

        date_time_after:
          type: string
          description: Local date and time immediately after the DST change.
          example: "2026-03-29 TIME 03:00"

        date_time_before:
          type: string
          description: Local date and time immediately before the DST change.
          example: "2026-03-29 TIME 02:00"

        overlap:
          type: boolean
          description: Indicates whether clock time overlaps during the transition.
    TimezoneLocationFromIp:
      type: object
      description: |
        Geolocation information derived from an IP address lookup.

        This object appears when the timezone lookup is performed using
        the `ip` parameter, or when the API resolves the caller's IP
        automatically.

        It provides geographic details such as continent, country,
        administrative regions, and coordinates used to determine the
        corresponding timezone.
      properties:
        continent_code:
          type: string
          description: Two-letter continent code.
          example: "EU"

        continent_name:
          type: string
          description: Full name of the continent.
          example: "Europe"

        country_code2:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: "GB"

        country_code3:
          type: string
          description: ISO 3166-1 alpha-3 country code.
          example: "GBR"

        country_name:
          type: string
          description: Common name of the country.
          example: "United Kingdom"

        country_name_official:
          type: string
          description: Official name of the country.
          example: "United Kingdom of Great Britain and Northern Ireland"

        is_eu:
          type: boolean
          description: Indicates whether the country is a member of the European Union.

        state_prov:
          type: string
          description: State, province, or region name.
          example: "England"

        state_code:
          type: string
          description: Standardized state or region code.
          example: "GB-ENG"

        district:
          type: string
          description: District or administrative subdivision.
          example: "Greater London"

        city:
          type: string
          description: City name of the location.
          example: "London"

        zipcode:
          type: string
          description: ZIP or postal code of the location.
          example: "SW1A"

        latitude:
          type: string
          description: Latitude coordinate of the location.
          example: "51.50002"

        longitude:
          type: string
          description: Longitude coordinate of the location.
          example: "-0.19244"

    TimezoneLocationFromName:
      type: object
      description: |
        Geolocation information derived from geocoding a free-text location
        address.

        This object appears when the timezone lookup is performed using the
        `location` parameter. It has fewer fields than `TimezoneLocationFromIp`,
        since it is produced by geocoding the provided address rather than
        an IP lookup.
      properties:
        location_string:
          type: string
          description: Original location string provided in the request.
          example: "London, UK"

        country_name:
          type: string
          description: Common name of the country.
          example: "United Kingdom"

        state_prov:
          type: string
          description: State, province, or region name.
          example: "England"

        city:
          type: string
          description: City name of the location.
          example: "London"

        locality:
          type: string
          description: Smaller locality or neighborhood within the city.
          example: "Westminster"

        latitude:
          type: string
          description: Latitude coordinate of the location.
          example: "51.50002"

        longitude:
          type: string
          description: Longitude coordinate of the location.
          example: "-0.19244"


    TimezoneAirportDetails:
      type: object
      description: |
        Airport information returned when the timezone lookup is performed
        using `iata_code` or `icao_code`.

        Contains metadata about the airport including its geographic
        coordinates, country, and airport identifiers.
      properties:
        type:
          type: string
          description: Classification of the airport based on size and traffic.
          example: "large_airport"

        name:
          type: string
          description: Official name of the airport.
          example: "Hartsfield Jackson Atlanta International Airport"

        latitude:
          type: string
          description: Latitude coordinate of the airport.
          example: "33.63670"

        longitude:
          type: string
          description: Longitude coordinate of the airport.
          example: "-84.42810"

        elevation_ft:
          type: number
          description: Airport elevation above sea level measured in feet.
          example: 1026

        continent_code:
          type: string
          description: Two-letter continent code where the airport is located.
          example: "NA"

        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: "US"

        state_code:
          type: string
          description: State or province code where the airport is located.
          example: "US-GA"

        city:
          type: string
          description: City served by the airport.
          example: "Atlanta"

        iata_code:
          type: string
          description: Three-letter IATA airport identifier.
          example: "ATL"

        icao_code:
          type: string
          description: Four-letter ICAO airport identifier.
          example: "KATL"

        faa_code:
          type: string
          description: FAA location identifier used primarily in the United States.
          example: ""


    TimezoneLocodeDetails:
      type: object
      description: |
        City or logistics location information returned when the timezone
        lookup is performed using a UN/LOCODE.

        UN/LOCODE is a five-character identifier consisting of a two-letter
        country code followed by a three-character location identifier.
      properties:
        lo_code:
          type: string
          description: UN/LOCODE representing the city or logistics location.
          example: "DEBER"

        city:
          type: string
          description: Name of the city associated with the UN/LOCODE.
          example: "Berlin"

        state_code:
          type: string
          description: State or region code of the location.
          example: "BE"

        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: "DE"

        country_name:
          type: string
          description: Name of the country where the location exists.
          example: "Germany"

        location_type:
          type: string
          description: |
            Type of facilities available at the location such as port,
            rail terminal, road terminal, airport, or postal exchange.
          example: "Port, Rail Terminal, Road Terminal, Airport, Postal Exchange"

        latitude:
          type: string
          description: Latitude coordinate of the location.
          example: "52.51667"

        longitude:
          type: string
          description: Longitude coordinate of the location.
          example: "13.38333"

    UserAgentResponse:
      type: object
      description: |
        Parsed user agent details including browser, device, layout engine, and
        operating system information. Also indicates bots, crawlers, or malicious
        user agent strings.
      properties:
        user_agent_string:
          type: string
          description: The raw user agent string that was parsed.
          example: "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"
        name:
          type: string
          description: |
            Name of the detected agent (e.g. browser name, bot name, or `"Hacker"`
            if the string is malformed or contains injected scripts).
          example: "Safari"
        type:
          type: string
          description: |
            Type of the detected user agent. See possible values in the documentation.
          example: "Browser"
        version:
          type: string
          description: Full version string of the detected agent.
          example: "9.0.2"
        version_major:
          type: string
          description: Major version of the detected agent.
          example: "9"
        device:
          $ref: "#/components/schemas/Device"
        engine:
          $ref: "#/components/schemas/Engine"
        operating_system:
          $ref: "#/components/schemas/OperatingSystem"

    Device:
      type: object
      description: Hardware device information extracted from the user agent string.
      properties:
        name:
          type: string
          description: Name of the device (e.g. model name or manufacturer).
          example: "Apple Macintosh"
        type:
          type: string
          description: |
            Type of the device. See possible values in the documentation.
          example: "Desktop"
        brand:
          type: string
          description: Brand or manufacturer of the device.
          example: "Apple"
        cpu:
          type: string
          description: CPU architecture or model of the device. May be `"Unknown"`.
          example: "Intel"

    Engine:
      type: object
      description: Layout engine information extracted from the user agent string.
      properties:
        name:
          type: string
          description: Name of the layout engine (e.g. `"AppleWebKit"`, `"Blink"`, `"Gecko"`).
          example: "AppleWebKit"
        type:
          type: string
          description: |
            Type of the layout engine. See possible values in the documentation.
          example: "Browser"
        version:
          type: string
          description: Full version string of the layout engine. May be `"??"` if unknown.
          example: "601.3.9"
        version_major:
          type: string
          description: Major version of the layout engine. May be `"??"` if unknown.
          example: "601"

    OperatingSystem:
      type: object
      description: Operating system information extracted from the user agent string.
      properties:
        name:
          type: string
          description: Name of the operating system.
          example: "Mac OS"
        type:
          type: string
          description: |
            Type of the operating system. See possible values in the documentation.
          example: "Desktop"
        version:
          type: string
          description: Full version string of the operating system. May be `"??"` if unknown.
          example: "10.11.2"
        version_major:
          type: string
          description: Major version of the operating system. May be `"??"` if unknown.
          example: "10.11"
        build:
          type: string
          description: Build identifier of the operating system. May be `"??"` if unknown.
          example: "??"

    AstronomyLookupResponse:
      type: object
      description: |
        Response returned by the single-date Astronomy Lookup API.

        Contains a `location` object with geolocation details for the
        resolved location, and an `astronomy` object with astronomical
        event times and positional data for the requested date.

        The `location` object structure varies based on the lookup method:
        - Coordinate or location-based lookups return basic geographic fields.
        - IP-based lookups return extended geolocation fields including
          continent, country codes, district, and zipcode.
      properties:
        ip:
          type: string
          description: |
            The IP address used for the astronomy lookup. Returned only when
            the lookup is performed using the `ip` parameter or when the API
            resolves the caller's IP automatically (no parameters provided).
          example: "8.8.8.8"

        location:
          $ref: "#/components/schemas/Location"

        astronomy:
          $ref: "#/components/schemas/AstronomyData"

    AstronomyTimeSeriesResponse:
      type: object
      description: |
        Response returned by the Astronomy Time Series API.

        Contains a `location` object and an `astronomy` array where each
        element represents astronomical data for a single day within the
        requested date range.

        Note that real-time positional data (sun/moon altitude, azimuth,
        distance, parallactic angle, illumination) is not included in time
        series responses.
      properties:
        ip:
          type: string
          description: |
            The IP address used for the astronomy lookup. Returned only when
            the lookup is performed using the `ip` parameter or when the API
            resolves the caller's IP automatically.
          example: "8.8.8.8"

        location:
          $ref: "#/components/schemas/Location"

        astronomy:
          type: array
          description: |
            Array of daily astronomical records covering the requested date
            range. Each entry contains event times for one calendar day.
          items:
            $ref: "#/components/schemas/AstronomyTimeSeriesEntry"

    Location:
      type: object
      description: |
        Geolocation information associated with the resolved location.

        For coordinate-based or location-string lookups, only basic geographic
        fields are returned (latitude, longitude, country, state, city, locality,
        elevation).

        For IP-based lookups, extended fields are also returned including
        continent codes, country codes, district, zipcode, and other metadata.
      properties:
        location_string:
          type: string
          description: |
            The location string provided in the request. Only present when the
            `location` query parameter was used.
          example: "New York, USA"

        continent_code:
          type: string
          description: Two-letter continent code. Returned for IP-based lookups only.
          example: "NA"

        continent_name:
          type: string
          description: Full name of the continent. Returned for IP-based lookups only.
          example: "North America"

        country_code2:
          type: string
          description: |
            ISO 3166-1 alpha-2 country code. Returned for IP-based lookups only.
          example: "US"

        country_code3:
          type: string
          description: |
            ISO 3166-1 alpha-3 country code. Returned for IP-based lookups only.
          example: "USA"

        country_name:
          type: string
          description: Common name of the country.
          example: "United States"

        country_name_official:
          type: string
          description: |
            Official name of the country. Returned for IP-based lookups only.
          example: "United States of America"

        is_eu:
          type: boolean
          description: |
            Indicates whether the country is a member of the European Union.
            Returned for IP-based lookups only.

        state_prov:
          type: string
          description: State, province, or region name.
          example: "New York"

        state_code:
          type: string
          description: |
            Standardized state or region code. Returned for IP-based lookups only.
          example: "US-NY"

        district:
          type: string
          description: |
            District or administrative subdivision. Returned for IP-based
            lookups only.
          example: "Manhattan"

        city:
          type: string
          description: City name of the location.
          example: "New York"

        locality:
          type: string
          description: Smaller locality or neighborhood within the city.
          example: "Midtown West"

        zipcode:
          type: string
          description: |
            ZIP or postal code of the location. Returned for IP-based
            lookups only.
          example: "10001"

        latitude:
          type: string
          format: float
          description: Latitude coordinate of the resolved location.
          example: "40.76473"

        longitude:
          type: string
          format: float
          description: Longitude coordinate of the resolved location.
          example: "-74.00084"

        elevation:
          type: string
          description: |
            Elevation in meters of the nearest known city, as a string. Empty string when
            not available. It does not echo the `elevation` request parameter.
          example: "9"

    TwilightPhase:
      type: object
      description: |
        Twilight phase times for either the morning (pre-sunrise) or evening
        (post-sunset) period.

        Includes astronomical, nautical, and civil twilight windows, as well
        as blue hour and golden hour windows commonly used in photography.

        All times are in `HH:mm` format by default. When the `time_zone`
        parameter is provided, times are returned as full date-time values
        in `yyyy-MM-dd HH:mm` format.
      properties:
        astronomical_twilight_begin:
          type: string
          description: |
            Start of astronomical twilight. In the morning, this is the end of night
            (same as `night_end`). In the evening, it is the end of nautical twilight;
            night starts at the evening `astronomical_twilight_end` (same as
            `night_begin`).
          example: "04:49"

        astronomical_twilight_end:
          type: string
          description: End of astronomical twilight.
          example: "05:21"

        nautical_twilight_begin:
          type: string
          description: |
            Start of nautical twilight, when the horizon first becomes visible.
          example: "05:21"

        nautical_twilight_end:
          type: string
          description: End of nautical twilight.
          example: "05:53"

        civil_twilight_begin:
          type: string
          description: |
            Start of civil twilight, when there is enough light for outdoor
            activities without artificial lighting.
          example: "05:53"

        civil_twilight_end:
          type: string
          description: End of civil twilight.
          example: "06:20"

        blue_hour_begin:
          type: string
          description: |
            Start of the blue hour, a period of soft diffused light with a
            blue color tone.
          example: "05:42"

        blue_hour_end:
          type: string
          description: End of the blue hour.
          example: "06:03"

        golden_hour_begin:
          type: string
          description: |
            Start of the golden hour, a period of warm low-angle light
            favored by photographers.
          example: "06:03"

        golden_hour_end:
          type: string
          description: End of the golden hour.
          example: "06:57"

    AstronomyData:
      type: object
      description: |
        Astronomical data for the resolved location and requested date.

        Includes event times for sunrise, sunset, moonrise, moonset,
        twilight phases, golden hour, blue hour, solar noon, and
        astronomical midnight, as well as real-time positional data
        for the Sun and Moon at the current time of day.

        All timestamp fields (except `current_time` and `day_length`) are
        in `HH:mm` format by default. When the `time_zone` parameter is
        provided, they are returned as full date-time values in
        `yyyy-MM-dd HH:mm` format.
      properties:
        time_zone:
          type: string
          description: |
            The IANA timezone identifier used for timestamp conversion.
            This field appears only when the `time_zone` query parameter
            was provided in the request.
          example: "Europe/London"

        date:
          type: string
          description: The date for which astronomical data is returned, in `yyyy-MM-dd` format.
          example: "2026-03-18"

        current_time:
          type: string
          description: |
            Current time in `HH:mm:ss.SSS` format, in the location's time zone, or in
            `time_zone` when that parameter is given. Positional values are calculated
            for this time. Without `date`, the current date is also taken in that time
            zone.
          example: "10:15:00.000"

        mid_night:
          type: string
          description: |
            Astronomical midnight (nadir) for the given date, in `HH:mm` format.
          example: "00:06"

        night_end:
          type: string
          description: |
            End of night / start of astronomical twilight in the morning,
            in `HH:mm` format.
          example: "04:49"

        morning:
          $ref: "#/components/schemas/TwilightPhase"

        sunrise:
          type: string
          description: |
            Time at which the sun rises at the resolved location, in `HH:mm`
            format. Returns `"-:-"` if the sun does not rise on this date
            (polar day or polar night).
          example: "06:20"

        sunset:
          type: string
          description: |
            Time at which the sun sets at the resolved location, in `HH:mm`
            format. Returns `"-:-"` if the sun does not set on this date
            (polar day or polar night).
          example: "19:00"

        evening:
          $ref: "#/components/schemas/TwilightPhase"

        night_begin:
          type: string
          description: |
            Start of night / end of astronomical twilight in the evening,
            in `HH:mm` format.
          example: "20:31"

        sun_status:
          type: string
          description: |
            Represents the current state of the sun relative to the horizon:

            - `"-"` — Normal day with both sunrise and sunset occurring.
            - `"Always above the twilight angle"` — The sun does not set
              (perpetual daylight, e.g. polar summer).
            - `"Always below the twilight angle"` — The sun does not rise
              within the current 24-hour period (e.g. polar night).
          example: "-"

        solar_noon:
          type: string
          description: |
            The time when the sun is at its highest point in the sky,
            in `HH:mm` format.
          example: "12:40"

        day_length:
          type: string
          description: |
            Total length of daylight for the date, from sunrise to sunset,
            in `HH:mm` format. Returns `"-:-"` if sunrise or sunset does
            not occur on this date (polar day or polar night).
          example: "12:40"

        sun_altitude:
          type: number
          format: float
          description: |
            The sun's altitude angle above the horizon at `current_time`,
            measured in degrees. Negative values indicate the sun is below
            the horizon.
          example: 42.5

        sun_distance:
          type: number
          format: float
          description: |
            Distance from Earth to the sun at `current_time`, in kilometers.
          example: 148900000.0

        sun_azimuth:
          type: number
          format: float
          description: |
            The azimuth angle of the sun at `current_time`, indicating its
            compass direction in degrees (0° = North, 90° = East, etc.).
          example: 150.3

        moon_phase:
          type: string
          description: |
            The current phase of the moon, indicating its position in the
            lunar cycle.
          enum:
            - NEW_MOON
            - WAXING_CRESCENT
            - FIRST_QUARTER
            - WAXING_GIBBOUS
            - FULL_MOON
            - WANING_GIBBOUS
            - LAST_QUARTER
            - WANING_CRESCENT
          example: "WAXING_CRESCENT"

        moonrise:
          type: string
          description: |
            Time at which the moon rises at the resolved location, in `HH:mm`
            format. Returns `"-:-"` if the moon does not rise on this date.
          example: "08:45"

        moonset:
          type: string
          description: |
            Time at which the moon sets at the resolved location, in `HH:mm`
            format. Returns `"-:-"` if the moon does not set on this date.
          example: "22:10"

        moon_status:
          type: string
          description: |
            Represents the current state of the moon relative to the horizon:

            - `"-"` — Normal day with both moonrise and moonset occurring.
            - `"Always above the horizon"` — The moon does not set within
              the current 24-hour period.
            - `"Always below the horizon"` — The moon does not rise within
              the current 24-hour period.
          example: "-"

        moon_altitude:
          type: number
          format: float
          description: |
            The moon's altitude angle above the horizon at `current_time`,
            measured in degrees. Negative values indicate the moon is below
            the horizon.
          example: 15.2

        moon_distance:
          type: number
          format: float
          description: |
            Distance from Earth to the moon at `current_time`, in kilometers.
          example: 384400.0

        moon_azimuth:
          type: number
          format: float
          description: |
            The azimuth angle of the moon at `current_time`, indicating its
            compass direction in degrees.
          example: 220.5

        moon_parallactic_angle:
          type: number
          format: float
          description: |
            The angle between the celestial pole and the moon's position
            relative to the observer's location, measured in degrees.
          example: 30.1

        moon_illumination_percentage:
          type: string
          description: |
            The percentage of the moon's surface illuminated by sunlight
            as viewed from Earth. Returned as a string with two decimal
            places. Negative values indicate a waning phase.
          example: "25.40"

        moon_angle:
          type: number
          format: float
          description: |
            The moon-sun ecliptic elongation angle, normalized to the
            0–360° range. This is the phase angle used to derive
            `moon_phase` and `moon_illumination_percentage`; it is not
            the moon's angular diameter.
          example: 357.01

    AstronomyTimeSeriesEntry:
      type: object
      description: |
        Astronomical data for a single calendar day within the time series
        response.

        Contains event times for sunrise, sunset, moonrise, moonset,
        twilight phases, solar noon, and day length.

        Note: Real-time positional data (sun/moon altitude, azimuth,
        distance, parallactic angle, illumination percentage, and moon
        angle) is not included in time series entries.
      properties:
        time_zone:
          type: string
          description: |
            The IANA timezone identifier used for timestamp conversion.
            This field appears only when the `time_zone` query parameter
            was provided in the request.
          example: "Europe/London"

        date:
          type: string
          description: The calendar date for this entry, in `yyyy-MM-dd` format.
          example: "2026-03-18"

        mid_night:
          type: string
          description: Astronomical midnight (nadir) for the given date.
          example: "00:06"

        night_end:
          type: string
          description: End of night / start of astronomical twilight in the morning.
          example: "04:49"

        morning:
          $ref: "#/components/schemas/TwilightPhase"

        sunrise:
          type: string
          description: |
            Time at which the sun rises, in `HH:mm` format. Returns `"-:-"`
            if the sun does not rise on this date.
          example: "06:20"

        sunset:
          type: string
          description: |
            Time at which the sun sets, in `HH:mm` format. Returns `"-:-"`
            if the sun does not set on this date.
          example: "19:00"

        evening:
          $ref: "#/components/schemas/TwilightPhase"

        night_begin:
          type: string
          description: Start of night / end of astronomical twilight in the evening.
          example: "20:31"

        sun_status:
          type: string
          description: |
            Current state of the sun relative to the horizon. See
            `AstronomyData.sun_status` for possible values.
          example: "-"

        solar_noon:
          type: string
          description: Time when the sun is at its highest point in the sky.
          example: "12:40"

        day_length:
          type: string
          description: |
            Total daylight duration from sunrise to sunset, in `HH:mm`
            format. Returns `"-:-"` if sunrise or sunset does not occur
            on this date (polar day or polar night).
          example: "12:40"

        moon_phase:
          type: string
          description: The phase of the moon on this date.
          enum:
            - NEW_MOON
            - WAXING_CRESCENT
            - FIRST_QUARTER
            - WAXING_GIBBOUS
            - FULL_MOON
            - WANING_GIBBOUS
            - LAST_QUARTER
            - WANING_CRESCENT
          example: "WAXING_CRESCENT"

        moonrise:
          type: string
          description: |
            Time at which the moon rises, in `HH:mm` format. Returns `"-:-"`
            if the moon does not rise on this date.
          example: "08:45"

        moonset:
          type: string
          description: |
            Time at which the moon sets, in `HH:mm` format. Returns `"-:-"`
            if the moon does not set on this date.
          example: "22:10"

        moon_status:
          type: string
          description: |
            Current state of the moon relative to the horizon. See
            `AstronomyData.moon_status` for possible values.
          example: "-"