openapi.yaml

openapi: 3.0.7
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` and require an API key passed as the `apiKey` query parameter.
    
    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 endpoint 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.
  - 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:
      name: IPGeolocaiton API
      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: "ipgeolocation.io"
        - name: lang
          in: query
          required: false
          description: |
            Language code for translated location names. Defaults to `en`. Non-English
            responses require a paid plan. Free plans always receive English regardless
            of this parameter. Unsupported `lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`. Defaults to `en`.

          schema:
            type: string
            default: "en"


        - 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.

            Free plan behavior for `include=*`: the API returns HTTP 200 and ignores the
            include request, returning only base response fields. In contrast, specific
            include values such as `include=security` return HTTP 401 on free plans.
          schema:
            type: string
            example: "*"
        - 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: `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.

            If the same field or object is specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.
            If the same field or object is specified in `include`, `fields`, and `excludes`,
            `include` takes priority over both `fields` and `excludes`.

            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 field paths are ignored. The API still returns HTTP 200.

            Available on all plans including Free.
          schema:
            type: string
            example: "location.city,security.threat_score,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: `location.continent_code`.
            To exclude an entire object, use the object key: `currency`, `time_zone`.

            If the same field or object is specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.
            If the same field or object is specified in `include`, `fields`, and `excludes`,
            `include` takes priority over both `fields` and `excludes`.

            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`). If both are provided, the `output` parameter
            takes precedence.

            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
            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: ""
                      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).
            - For the `ipgeo-bulk` endpoint:
              - The request payload is empty or missing.
              - The JSON body is malformed.
              - The `ips` field is missing or the `ips` array is empty.
              - More than 50,000 IP addresses are provided in the request.
            - 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."
                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"
                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"
                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:

            - The `apiKey` URL parameter is missing.
            - An invalid (random or incorrect) API key is provided.
            - The account has been disabled or 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 account’s active-until date has passed and renewal or upgrade is required.
            - 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`.
            - The bulk IP geolocation endpoint is called using a Free subscription API key.
            - 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.
            - 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"
                lockedAccount:
                  summary: Account locked or disabled
                  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."
                expiredSubscription:
                  summary: Subscription expired or trial ended
                  value:
                    message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
                freePlanBulk:
                  summary: Free plan used for bulk endpoint
                  value:
                    message: "Bulk IP to geolocation lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
                requestOriginBulk:
                  summary: Bulk endpoint called using Request Origin authentication
                  value:
                    message: "Bulk queries are not allowed with request origins. Please use some API key to perform bulk queries."
                freePlanInclude:
                  summary: Free plan used with restricted include parameter
                  value:
                    message: "This feature 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."
        "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, 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 IPv4 or IPv6 address does not 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. Calling it with a free
        plan API key returns HTTP 401.

        The response is a JSON array with one element per IP in the request. Each element
        is either a full geolocation response object or an error object with only a
        `message` field. Invalid, bogon, and unresolvable entries appear as error
        objects. Invalid, private, and bogon IPs are not billed.

        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`. Non-English
            responses require a paid plan. Free plans always receive English regardless
            of this parameter. Unsupported `lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`. Defaults to `en`.
          schema:
            type: string
            default: "en"


        - 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.

            Free plan behavior for `include=*`: the API returns HTTP 200 and ignores the
            include request, returning only base response fields. In contrast, specific
            include values such as `include=security` return HTTP 401 on free plans.
          schema:
            type: string
            example: "*"
        - 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: `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.

            If the same field or object is specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.
            If the same field or object is specified in `include`, `fields`, and `excludes`,
            `include` takes priority over both `fields` and `excludes`.

            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 field paths are ignored. The API still returns HTTP 200.

            Available on all plans including Free.
          schema:
            type: string
            example: "location.city,security.threat_score,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: `location.continent_code`.
            To exclude an entire object, use the object key: `currency`, `time_zone`.

            If the same field or object is specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.
            If the same field or object is specified in `include`, `fields`, and `excludes`,
            `include` takes priority over both `fields` and `excludes`.

            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`). If both are provided, the `output` parameter
            takes precedence.

            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
            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:
                    - "1.1.1.1"
                    - "8.8.4.4"
                    - "165.227.0.0"
      responses:
        "200":
          description: |
            An array of results, one per input entry. Valid entries return full
            geolocation objects. Invalid, bogon, and unresolvable entries return
            objects with only a `message` field.
            `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: 3
            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: 4
          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 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).
            - For the `ipgeo-bulk` endpoint:
              - The request payload is empty or missing.
              - The JSON body is malformed.
              - The `ips` field is missing or the `ips` array is empty.
              - More than 50,000 IP addresses are provided in the request.
            - 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."
                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"
                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"
                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:

            - The `apiKey` URL parameter is missing.
            - An invalid (random or incorrect) API key is provided.
            - The account has been disabled or 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 account’s active-until date has passed and renewal or upgrade is required.
            - 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`.
            - The bulk IP geolocation endpoint is called using a Free subscription API key.
            - 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.
            - 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"
                lockedAccount:
                  summary: Account locked or disabled
                  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."
                expiredSubscription:
                  summary: Subscription expired or trial ended
                  value:
                    message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
                freePlanBulk:
                  summary: Free plan used for bulk endpoint
                  value:
                    message: "Bulk IP to geolocation lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
                requestOriginBulk:
                  summary: Bulk endpoint called using Request Origin authentication
                  value:
                    message: "Bulk queries are not allowed with request origins. Please use some API key to perform bulk queries."
                freePlanInclude:
                  summary: Free plan used with restricted include parameter
                  value:
                    message: "This feature 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."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "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: "1.1.1.1"
            application/xml:
              schema:
                $ref: "#/components/schemas/GetIpResponse"
              example: |
                <LinkedHashMap>
                  <ip>1.1.1.1</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: "1.1.1.1"
              example: "1.1.1.1"
        "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:
    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 specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.

            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 field paths are ignored. The API still returns HTTP 200.

            Available on all plans including Free.
          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 specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.

            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: "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`). If both are provided, the `output` parameter
            takes precedence.

            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
            default: json
      responses:
        "200":
          description: Security intelligence for the requested IP.
          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/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"
                  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.
            - Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,
              either in a parameter name or its value (especially in the API key).
            - For the `security-bulk` endpoint:
              - The request payload is empty or missing.
              - The JSON body is malformed.
              - The `ips` field is missing or the `ips` array is empty.
              - More than 50,000 IP addresses are provided in the request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidIp:
                  summary: Invalid IPv4/IPv6 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."
                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"
                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 has been disabled or 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.
            - The account’s active-until date has passed and renewal or upgrade is required.
            - A domain name is passed in the `ip` parameter when calling the IP Security API.
            - 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"

                lockedAccount:
                  summary: Account locked or disabled
                  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 IP Security API
                  value:
                    message: "IP Security API is not supported on your current subscription. This feature is available on paid subscriptions only."

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

                expiredSubscription:
                  summary: Subscription expired or trial ended
                  value:
                    message: "Your subscription has expired. Please subscribe to a paid plan to continue using IPGeolocation API."

                domainLookupNotSupported:
                  summary: Domain lookup used with Security API
                  value:
                    message: "Domain lookup is not supported for the IP Security 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."
        "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, 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 IPv4 or IPv6 address does not 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/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. Invalid, bogon, or private
        IP addresses return an object containing only a `message` field.

        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 specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.

            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 field paths are ignored. The API still returns HTTP 200.

            Available on all plans including Free.
          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 specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.

            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: "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`). If both are provided, the `output` parameter
            takes precedence.

            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
            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:
                    - "1.1.1.1"
                    - "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, private, or bogon IP addresses return an object containing only
            a `message` field.

            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: 3
            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: 4
          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"
                    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 one of the following reasons:

            - The provided IPv4 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).
            - For the `security-bulk` endpoint:
              - The request payload is empty or missing.
              - The JSON body is malformed.
              - The `ips` field is missing or the `ips` array is empty.
              - More than 50,000 IP addresses are provided in the request.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                invalidIp:
                  summary: Invalid IPv4/IPv6 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."
                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"
                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 has been disabled or 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.
            - The account’s active-until date has passed and renewal or upgrade is required.
            - A domain name is passed in the `ip` parameter when calling the IP Security API.
            - 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"

                lockedAccount:
                  summary: Account locked or disabled
                  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 IP Security API
                  value:
                    message: "IP Security API is not supported on your current subscription. This feature is available on paid subscriptions only."

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

                expiredSubscription:
                  summary: Subscription expired or trial ended
                  value:
                    message: "Your subscription has expired. Please subscribe to a paid plan to continue using IPGeolocation API."

                domainLookupNotSupported:
                  summary: Domain lookup used with Security API
                  value:
                    message: "Domain lookup is not supported for the IP Security 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."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "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 the `asn` parameter is provided, the `ip` parameter must not be used,
            because the lookup will be performed directly using the specified ASN.

            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,
            and the `ip` parameter must not be included in the request.

            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).

          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`

            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.

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

            If the same field or object is specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.

            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 field paths are ignored. The API still returns HTTP 200.

            Available on all plans including Free.

          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.

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

            If the same field or object is specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.

            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: "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`). If both are provided, the `output` parameter
            takes precedence.

            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
            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:

            - A syntactically valid IPv4, IPv6, or ASN does not exist in the IPGeolocation database.
            - An IPv4, IPv6, or ASN 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/ASN not found in database
                  value:
                    message: "Provided ASN or IP Address does not 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."
                asnAsPathVariable:
                  summary: ASN passed as path variable instead of query parameter
                  value:
                    message: "No endpoint GET /v3/ipgeo/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.
            - 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 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."
        "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 has been disabled or 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.
            - The account’s active-until date has passed and renewal or upgrade is required.
          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"
                lockedAccount:
                  summary: Account locked or disabled
                  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 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."
                expiredSubscription:
                  summary: Subscription expired or trial ended
                  value:
                    message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
        "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 role, 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 specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.

            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 field paths are ignored. The API still returns HTTP 200.

            Available on all plans including Free.
          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 specified in both `fields` and `excludes`, the
            object is still returned, but it will be empty.

            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: "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`). If both are provided, the `output` parameter
            takes precedence.

            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
            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: "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"
        "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/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 IPv4 or IPv6 address does not 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/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 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."
        "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 has been disabled or 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.
            - The account’s active-until date has passed and renewal or upgrade is required.
          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"
                lockedAccount:
                  summary: Account locked or disabled
                  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."
                expiredSubscription:
                  summary: Subscription expired or trial ended
                  value:
                    message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
        "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/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`

        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 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: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"

        - name: lang
          in: query
          required: false
          description: |
            Language code for translated location names. Defaults to `en`. Non-English
            responses require a paid plan. Free plans always receive English regardless
            of this parameter. Unsupported `lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`. Defaults to `en`.
          schema:
            type: string
            default: "en"


        - 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`). If both are provided, the `output` parameter
            takes precedence.

            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
            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 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: "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.

            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.

            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 to retrieve timezone information.

            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.

            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'
              example:
                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
        "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.
            
              - 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidIp:
                  summary: Invalid IPv4 or IPv6 address
                  value:
                    message: "Provided name, service or IP address '999.999.999.999' is not valid."
                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."
                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"

        "401":
          description: |
            Unauthorized – Possible reasons include:
              - Missing or invalid API key
              - If your account has been disabled or locked to use by the admin 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.
              - If your active until date has passed and you need to upgrade your account.
              - 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"
                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."
                expiredSubscription:
                  summary: Subscription expired
                  value:
                    message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
                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."
        "404":
          description: |
            Not found. Returned for one of the following reasons:
            - If the IPv4, IPv6 address does not exist in our database.

            - If the IPv4, IPv6 address passed as a path variable, instead of url parameter as ip=.
            
            - If the location address provided to the `location` parameter is invalid, or if the address provided to either `location_from` or `location_to` is invalid for time conversion. 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:
                ipNotInDatabase:
                  summary: IPv4/IPv6 not found in database
                  value:
                    message: "Provided IPv4 or IPv6 address does not 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."
                invalidLocation:
                  summary: Invalid location
                  value:
                    message: "We couldn't find the (to) location (Germany, jaakjsdfjhb8wobv). Try a city or state level address only."
                invalidAirportCode:
                  summary: Invalid airport code
                  value:
                    message: "Provided IATA or ICAO code does not exist in our database."
                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/ServiceUnavailable"
        "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 HH:mm`
        - `yyyy-MM-dd HH:mm:ss`

        If the `time` parameter is omitted, the current time is used
        for conversion.

        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 HH:mm`
            - `yyyy-MM-dd HH:mm:ss`

            If omitted, the current time 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
          schema:
            type: string
            example: "YSSY"

        - name: icao_to
          in: query
          required: false
          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`). If both are provided, the `output` parameter
            takes precedence.

            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
            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.
            
              - 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 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` 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."
                invalidTimezone:
                  summary: Invalid timezone identifier
                  value:
                    message: "Check whether your input values are correct; time_zone_name = Europe/InvalidCity"
                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:
              - Missing or invalid API key
              - If your account has been disabled or locked to use by the admin 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.
              - If your active until date has passed and you need to upgrade your account.
          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"
                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."
                expiredSubscription:
                  summary: Subscription expired
                  value:
                    message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
        "404":
          description: |
            Not found. Returned for one of the following reasons:
            - If the IPv4, IPv6 address does not exist in our database.

            - If the IPv4, IPv6 address passed as a path variable, instead of url parameter as ip=.
            
            - If the location address provided to the `location` parameter is invalid, or if the address provided to either `location_from` or `location_to` is invalid for time conversion. 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:
                ipNotInDatabase:
                  summary: IPv4/IPv6 not found in database
                  value:
                    message: "Provided IPv4 or IPv6 address does not 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."
                invalidLocation:
                  summary: Invalid location
                  value:
                    message: "We couldn't find the (to) location (Germany, jaakjsdfjhb8wobv). Try a city or state level address only."
                invalidAirportCode:
                  summary: Invalid airport code
                  value:
                    message: "Provided IATA or ICAO code does not exist in our database."
                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/ServiceUnavailable"
        "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 — Auto-detect caller's user agent:**
        Omit the `User-Agent` header entirely. The API will parse the user agent string
        of the calling client automatically. 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. When omitted, the API automatically parses
            the user agent of the calling client. When provided, the supplied string is
            parsed instead.
          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)"

      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 `uaStrings` array is empty, or the JSON body does not contain a `uaStrings`
            field when calling `/v3/user-agent-bulk`.
          - More than 50,000 user agent strings are provided in a single bulk request.
        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"
              emptyBulkList:
                summary: Empty uaStrings array or missing field
                value:
                  message: "User-Agent strings for bulk lookup are missing"
              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 has been disabled or locked due to illegal activity.
            - Requests are made after the subscription trial has expired.
            - The subscription is paused or not active.
            - The account’s active-until date has passed.
            - A paid feature is accessed using a free subscription.
            - The bulk user agent parsing endpoint 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."
                lockedAccount:
                  summary: Account locked or disabled
                  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 has expired. Please subscribe to a paid plan to continue using IPGeolocation API."
                inactiveSubscription:
                  summary: Subscription inactive or paused
                  value:
                    message: "Your subscription is not active."
                expiredAccount:
                  summary: Account active-until date passed
                  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."
                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."
        "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/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/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


      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 `uaStrings` array is empty, or the JSON body does not contain a `uaStrings`
            field when calling `/v3/user-agent-bulk`.
          - More than 50,000 user agent strings are provided in a single bulk request.
        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"
              emptyBulkList:
                summary: Empty uaStrings array or missing field
                value:
                  message: "User-Agent strings for bulk lookup are missing"
              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 has been disabled or locked due to illegal activity.
            - Requests are made after the subscription trial has expired.
            - The subscription is paused or not active.
            - The account’s active-until date has passed.
            - A paid feature is accessed using a free subscription.
            - The bulk user agent parsing endpoint 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."
                lockedAccount:
                  summary: Account locked or disabled
                  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 has expired. Please subscribe to a paid plan to continue using IPGeolocation API."
                inactiveSubscription:
                  summary: Subscription inactive or paused
                  value:
                    message: "Your subscription is not active."
                expiredAccount:
                  summary: Account active-until date passed
                  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."
                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."
        "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/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/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 in the array
        is parsed independently. The total credits charged equals the number of strings
        in the array.

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

      tags:
        - User Agent

      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
                  minItems: 1
                  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: "??"
        "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 `uaStrings` array is empty, or the JSON body does not contain a `uaStrings`
            field when calling `/v3/user-agent-bulk`.
          - More than 50,000 user agent strings are provided in a single bulk request.
        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"
              emptyBulkList:
                summary: Empty uaStrings array or missing field
                value:
                  message: "User-Agent strings for bulk lookup are missing"
              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 has been disabled or locked due to illegal activity.
            - Requests are made after the subscription trial has expired.
            - The subscription is paused or not active.
            - The account’s active-until date has passed.
            - A paid feature is accessed using a free subscription.
            - The bulk user agent parsing endpoint 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."
                lockedAccount:
                  summary: Account locked or disabled
                  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 has expired. Please subscribe to a paid plan to continue using IPGeolocation API."
                inactiveSubscription:
                  summary: Subscription inactive or paused
                  value:
                    message: "Your subscription is not active."
                expiredAccount:
                  summary: Account active-until date passed
                  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."
                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."
        "405":
          $ref: "#/components/responses/MethodNotAllowed"
        "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 angular diameter

        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`

        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 at the resolved location.
          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.

            Defaults to `0` if not provided. Maximum allowed value is
            **10,000 meters**. Negative values are treated as `0`.
          schema:
            type: number
            format: double
            default: 0
            minimum: 0
            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. Free
            plans always receive English regardless of this parameter. Unsupported
            `lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`. Defaults to `en`.
          schema:
            type: string
            default: "en"

      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: 0.52
        "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 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**.
              - If the provided `elevation` value exceeds the maximum allowed
                value of **10,000 meters**.
              - If the provided `time_zone` is invalid or unrecognized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidIp:
                  summary: Invalid IPv4 or IPv6 address
                  value:
                    message: "Provided name, service or IP address '999.999.999.999' is not valid."
                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"
                invalidCoordinates:
                  summary: Coordinates out of range
                  value:
                    message: "Longitude must be between -180 and 180 or latitude must be between -90 and 90."
                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 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."

        "401":
          description: |
            Unauthorized – Possible reasons include:
              - Missing or invalid API key.
              - If your account has been disabled or locked by the admin 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.
              - If your active-until date has passed and you need to renew
                or upgrade your subscription.
              - 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"
                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."
                expiredSubscription:
                  summary: Subscription expired
                  value:
                    message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
                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."
        "404":
          description: |
            Not Found. Returned for one of the following reasons:
              - If the IPv4 or IPv6 address does not exist in the database.
              - If the IPv4 or IPv6 address is passed as a path variable instead
                of 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:
                ipNotInDatabase:
                  summary: IP not found in database
                  value:
                    message: "Provided IPv4 or IPv6 address does not exist in our database."
                invalidLocation:
                  summary: Invalid location address
                  value:
                    message: "We couldn't find the location 'InvalidCity, XX'. Try a city or state level 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/ServiceUnavailable"
        "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 maximum allowed span between `dateStart` and `dateEnd` is
          **90 days**.
        - 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 maximum allowed span between
            `dateStart` and `dateEnd` is **90 days**.
          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 maximum allowed span between
            `dateStart` and `dateEnd` is **90 days**.
          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.

            Defaults to `0` if not provided. Maximum allowed value is
            **10,000 meters**. Negative values are treated as `0`.
          schema:
            type: number
            format: double
            default: 0
            minimum: 0
            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. Free
            plans always receive English regardless of this parameter. Unsupported
            `lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`. Defaults to `en`.
          schema:
            type: string
            default: "en"

      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 the span between `dateStart` and `dateEnd` is greater than
                **90 days**.
              - If the provided values for `lat` and `long` are not numbers,
                or fall outside the acceptable ranges.
              - If the provided `elevation` value exceeds **10,000 meters**.
              - If the provided `time_zone` is invalid or unrecognized.
              - If an invalid or unsupported `lang` parameter is provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidIp:
                  summary: Invalid IPv4 or IPv6 address
                  value:
                    message: "Provided name, service or IP address '999.999.999.999' is not valid."
                specialCharacters:
                  summary: Invalid characters in request
                  value:
                    message: "Invalid character found in the request target."
                invalidDateFormat:
                  summary: Invalid date format
                  value:
                    message: "You must provide date in the 'yyyy-MM-dd' format"
                dateRangeExceeded:
                  summary: Date range exceeds 90 days
                  value:
                    message: "Date range cannot exceed 90 days."
                invalidCoordinates:
                  summary: Coordinates out of range
                  value:
                    message: "Longitude must be between -180 and 180 or latitude must be between -90 and 90."
                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 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."

        "401":
          description: |
            Unauthorized – Possible reasons include:
              - Missing or invalid API key.
              - If your account has been disabled or locked by the admin.
              - 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.
              - If your active-until date has passed.
              - 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"
                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."
                expiredSubscription:
                  summary: Subscription expired
                  value:
                    message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
                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."
        "404":
          description: |
            Not Found. Returned for one of the following reasons:
              - If the IPv4 or IPv6 address does not exist in the database.
              - If the IPv4 or IPv6 address is passed as a path variable instead
                of 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:
                ipNotInDatabase:
                  summary: IP not found in database
                  value:
                    message: "Provided IPv4 or IPv6 address does not exist in our database."
                invalidLocation:
                  summary: Invalid location address
                  value:
                    message: "We couldn't find the location 'InvalidCity, XX'. Try a city or state level 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/ServiceUnavailable"
        "504":
          $ref: "#/components/responses/GatewayTimeout"
        "505":
          $ref: "#/components/responses/HttpVersionNotSupported"

components:
  responses:
    MethodNotAllowed:
      description: |
        Method Not Allowed. Returned when an unsupported HTTP method is used
        to call an endpoint.

        Only GET and POST methods are supported:

        - `GET` is allowed for the `ipgeo` endpoint.
        - `POST` is allowed for the `ipgeo-bulk` endpoint.

        Any other HTTP method, or using the correct method on the wrong endpoint,
        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"
            postNotAllowedForSingle:
              summary: POST used on single lookup endpoint
              value:
                message: "Request method 'POST' is not supported"
            unsupportedMethod:
              summary: Unsupported HTTP method
              value:
                message: "Request method 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."

    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 a Paid subscription with
          status 'past due', 'deleted', or 'trial expired'.
        - 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_USAGE_LIMIT API credits per PLAN_INTERVAL for your subscribed PLAN plan. Please wait for your credits to reset, enable overage, 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 PLAN_USAGE_LIMIT_AND_SURCHARGE_LIMIT on your subscribed PLAN plan. Please wait for your credits to reset, enable a higher surcharge limit, 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. This usually happens when the client sets a very short request or
        connection timeout. Increase the timeout on the client side.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Client closed the request before the server could respond."

    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 on the server side."
    BadGateway:
      description: |
        Bad Gateway. The API server received an invalid response from an upstream
        server while processing the request. This is usually temporary.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Upstream service error. Please try again later."
    ServiceUnavailable:
      description: |
        Service Unavailable. The API is temporarily unavailable due to maintenance
        or overload. Please try again later.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "Service temporarily unavailable. Please try again later."
    GatewayTimeout:
      description: |
        Gateway Timeout. The API server did not receive a timely response from
        an upstream server.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "The server timed out while processing the request."
    HttpVersionNotSupported:
      description: |
        HTTP Version Not Supported. The server does not support the HTTP protocol
        version used in the request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            message: "HTTP version not supported."

  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: "1.1.1.1"
    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.
            Contains the original domain input exactly as submitted.
          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 is always present.
      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. Mirrors
            the domain value from the request.
          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.
          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"
        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 time at the IP's location. Observed formats include
            `YYYY-MM-DDTHH:mm:ss±ZZZZ` and `YYYY-MM-DD HH:mm:ss.SSS±ZZZZ`.
          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.
          oneOf:
            - $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.
          oneOf:
            - $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.
      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 name, service or 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"
        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"

    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:
          $ref: "#/components/schemas/TimezoneLocation"

        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"

        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: |
            Time difference between the source and destination
            timezones expressed in hours.
          example: 7.5

        diff_min:
          type: number
          description: |
            Time difference between the source and destination
            timezones expressed in minutes.
          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:
          format: float
          description: Standard timezone offset from UTC in hours.
          example: -8

        offset_with_dst:
          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 time at the IP's location. Observed formats include
            `YYYY-MM-DDTHH:mm:ss±ZZZZ` and `YYYY-MM-DD HH:mm:ss.SSS±ZZZZ`.
          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: Number of hours added during daylight saving time.

        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: |
        Represents a daylight saving time transition event including the
        moment when DST begins or ends.
      properties:
        utc_time:
          type: string
          description: UTC timestamp when the DST transition occurs.
          example: "2025-03-09 TIME 10"

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

        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: "2025-03-09 TIME 03"

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

        overlap:
          type: boolean
          description: Indicates whether clock time overlaps during the transition.
    TimezoneLocation:
      type: object
      description: |
        Geolocation information associated with the requested IP address
        or location query.

        This object appears when the timezone lookup is performed using
        the `ip` or `location` parameters.

        It provides geographic details such as continent, country,
        administrative regions, and coordinates used to determine the
        corresponding timezone.
      properties:
        location_string:
          type: string
          description: Original location string provided in the request.
          example: "London, UK"

        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"

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

        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"


    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 above sea level at the location, in meters.
          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 marks the
            end of night; in the evening, this marks the start of night sky.
          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 local time at the resolved location in `HH:mm:ss.SSS` format.
            Used as the reference time for real-time positional calculations
            (altitude, azimuth, distance).
          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.
          example: "06:20"

        sunset:
          type: string
          description: |
            Time at which the sun sets at the resolved location, in `HH:mm` format.
          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.
          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 angular diameter of the moon as observed from Earth,
            measured in degrees.
          example: 0.52

    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:
        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.
          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: "-"