Timezone

Resolve a timezone from name (e.g. America/New_York), IP address, or lat/long coordinates. Returns current date/time, UTC offset, DST status, DST transition windows, airport/locode metadata, and a convert endpoint to translate a timestamp between two zones.

OpenAPI Specification

ipgeolocation-timezone-openapi.yml Raw ↑
openapi: 3.0.7
info:
  title: 'IPGeolocation.io: Date, Time & Timezone API'
  version: "3.0"
  description: |
    Retrieve current date, time, and timezone information for a specific
    location or identifier.

    The Timezone API returns detailed timezone information including the
    timezone name, UTC offset, daylight saving time (DST) status, current
    local time, formatted timestamps, and upcoming DST transition details.

    Timezone information can be retrieved using multiple lookup inputs:

    - Timezone name (IANA identifier)
    - Location address
    - Geographic coordinates (latitude and longitude)
    - IPv4 or IPv6 address
    - IATA airport code
    - ICAO airport code
    - UN/LOCODE city identifier

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

    - Geolocation details for IP address or location queries
    - Airport information for IATA or ICAO code queries
    - City details for UN/LOCODE queries

    Two endpoints are available:

    - **Timezone lookup** (`GET /v3/timezone`) returns timezone and current
      time information for a location, IP address, coordinates, timezone
      name, airport code, or UN/LOCODE.

    - **Time conversion** (`GET /v3/timezone/convert`) converts a given time
      between two timezones, locations, coordinates, airports, or UN/LOCODE
      identifiers.

    ## Authentication

    Two authentication methods are supported:

    ### API Key

    Pass your API key as the `apiKey` query parameter on every request. You can find your
    key in the [IPGeolocation dashboard](https://app.ipgeolocation.io/). Store it in
    server-side environment variables. Avoid exposing it in client-side JavaScript.

    ### Request Origin (CORS)

    Available on paid plans only. Whitelist your domain in the dashboard under the
    "API Keys" section. Once configured, requests from that domain (and all its subdomains)
    are accepted without passing `apiKey`. Enter your root domain (e.g. `example.com`),
    not the full URL.

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

    | Plan | Extra API Keys + Request Origins |
    |---|---|
    | Starter (150K requests) | 1 |
    | Core (250K requests) | 1 |
    | Plus (500K requests) | 2 |
    | Pro (1M requests) | 2 |
    | Business (2M requests) | 3 |
    | Premium (5M requests) | 3 |

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

    ## Response Formats

    The API supports JSON (default) and XML output.

    - Set the `output` query parameter to `json` or `xml`.
    - Alternatively, set the `Accept` header to `application/json`,
      `application/xml`, or `text/xml`.

    If neither is specified, the response is returned as JSON. XML responses
    use a `LinkedHashMap` root element.

    ## Credit Usage

    Credits are charged only for successful **HTTP 200** responses. The exact
    number of credits consumed by a request is returned in the
    `X-Credits-Charged` response header.

    - A **timezone lookup** (`GET /v3/timezone`) consumes **1 credit** per request.
    - A **time conversion request** (`GET /v3/timezone/convert`) consumes **1 credit** per request.

    ## Lookup Parameter Priority

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

    1. `tz` (timezone name)
    2. Geographic coordinates (`lat`, `long`)
    3. `location`
    4. `ip`
    5. `iata_code`
    6. `icao_code`
    7. `lo_code`

    ## Parameter Name Casing

    Query parameter names are case-sensitive. Use exact names such as
    `apiKey`, `tz`, `location`, `lat`, `long`, `ip`, `iata_code`,
    `icao_code`, `lo_code`, `lang`, and `output`.

    ## Timezone Data Availability

    Basic timezone information is also included in the IP Geolocation API
    (`/v3/ipgeo`) for both Free and Paid subscriptions.

    Extended timezone metadata such as formatted timestamps, calendar
    fields, and additional date/time formats are available through the
    dedicated `/v3/timezone` endpoint.

    Both `/v3/ipgeo` and `/v3/timezone` endpoints are available on **Free
    and Paid plans**. The difference between them lies in the **level of
    timezone data returned**, not plan availability.

    | Field | /v3/ipgeo | /v3/timezone |
    |---|---|---|
    | time_zone.name | ✓ | ✓ |
    | time_zone.offset | ✓ | ✓ |
    | time_zone.offset_with_dst | ✓ | ✓ |
    | time_zone.current_time | ✓ | ✓ |
    | time_zone.current_time_unix | ✓ | ✓ |
    | time_zone.current_tz_abbreviation | ✓ | ✓ |
    | time_zone.current_tz_full_name | ✓ | ✓ |
    | time_zone.standard_tz_abbreviation | ✓ | ✓ |
    | time_zone.standard_tz_full_name | ✓ | ✓ |
    | time_zone.is_dst | ✓ | ✓ |
    | time_zone.dst_savings | ✓ | ✓ |
    | time_zone.dst_exists | ✓ | ✓ |
    | time_zone.dst_start | ✓ | ✓ |
    | time_zone.dst_end | ✓ | ✓ |
    | time_zone.date | ✗ | ✓ |
    | time_zone.date_time | ✗ | ✓ |
    | time_zone.date_time_txt | ✗ | ✓ |
    | time_zone.date_time_wti | ✗ | ✓ |
    | time_zone.date_time_ymd | ✗ | ✓ |
    | time_zone.time_24 | ✗ | ✓ |
    | time_zone.time_12 | ✗ | ✓ |
    | time_zone.week | ✗ | ✓ |
    | time_zone.month | ✗ | ✓ |
    | time_zone.year | ✗ | ✓ |
    | time_zone.year_abbr | ✗ | ✓ |

    Use `/v3/ipgeo` when timezone information is required together with
    geolocation, ASN, network, security, or company data in a single request.

    Use `/v3/timezone` when detailed timezone metadata, formatted time
    values, or timezone conversions are required.

    ## Usage Limits

    The Timezone API is available on **both Free and Paid plans**.

    Free plan subscriptions include **up to 1,000 requests per day**.

    Paid subscriptions do not enforce fixed daily or hourly rate limits.
    If the monthly request quota is exceeded, requests continue and a
    surcharge may be applied depending on the subscribed plan.

    Requests made using invalid API keys or unsupported subscriptions
    return **HTTP 401 Unauthorized**.

  contact:
    name: IPGeolocation Support
    url: https://ipgeolocation.io/contact.html
    email: [email protected]

  termsOfService: https://ipgeolocation.io/tos.html

  license:
    name: Proprietary
    url: https://ipgeolocation.io/tos.html

externalDocs:
  description: IPGeolocation Date, Time & Timezone API documentation
  url: https://ipgeolocation.io/documentation/timezone-api.html

servers:
- url: https://api.ipgeolocation.io
  description: Production
security:
- ApiKeyAuth: []
paths:
  /v3/timezone:
    get:
      operationId: lookupTimezone
      summary: IPGeolocation.io 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:
      - $ref: "#/components/parameters/Tz"
      - $ref: "#/components/parameters/Location"
      - $ref: "#/components/parameters/Lat"
      - $ref: "#/components/parameters/Long"
      - $ref: "#/components/parameters/Ip"
      - $ref: "#/components/parameters/IataCode"
      - $ref: "#/components/parameters/IcaoCode"
      - $ref: "#/components/parameters/LoCode"
      - $ref: "#/components/parameters/Lang"
      - $ref: "#/components/parameters/Output"
      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

            application/xml:
              schema:
                $ref: '#/components/schemas/TimezoneLookupResponse'
              example: |
                <LinkedHashMap>
                  <ip>49.12.0.0</ip>
                  <location>
                      <continent_code>EU</continent_code>
                      <continent_name>Europe</continent_name>
                      <country_code2>DE</country_code2>
                      <country_code3>DEU</country_code3>
                      <country_name>Germany</country_name>
                      <country_name_official>Federal Republic of Germany</country_name_official>
                      <is_eu>true</is_eu>
                      <state_prov>Bavaria</state_prov>
                      <state_code>DE-BY</state_code>
                      <district>Cham</district>
                      <city>Falkenstein</city>
                      <zipcode>93167</zipcode>
                      <latitude>49.09745</latitude>
                      <longitude>12.48637</longitude>
                  </location>
                  <time_zone>
                      <name>Europe/Berlin</name>
                      <offset>1</offset>
                      <offset_with_dst>1</offset_with_dst>
                      <date>2026-03-16</date>
                      <date_time>2026-03-16 21:01:46</date_time>
                      <date_time_txt>Monday, March 16, 2026 21:01:46</date_time_txt>
                      <date_time_wti>Mon, 16 Mar 2026 21:01:46 +0100</date_time_wti>
                      <date_time_ymd>2026-03-16T21:01:46+0100</date_time_ymd>
                      <current_time>2026-03-16 21:01:46.907+0100</current_time>
                      <current_time_unix>1773691306.907</current_time_unix>
                      <time_24>21:01:46</time_24>
                      <time_12>09:01:46 PM</time_12>
                      <week>12</week>
                      <month>3</month>
                      <year>2026</year>
                      <year_abbr>26</year_abbr>
                      <current_tz_abbreviation>CET</current_tz_abbreviation>
                      <current_tz_full_name>Central European Standard Time</current_tz_full_name>
                      <standard_tz_abbreviation>CET</standard_tz_abbreviation>
                      <standard_tz_full_name>Central European Standard Time</standard_tz_full_name>
                      <is_dst>false</is_dst>
                      <dst_savings>0</dst_savings>
                      <dst_exists>true</dst_exists>
                      <dst_tz_abbreviation>CEST</dst_tz_abbreviation>
                      <dst_tz_full_name>Central European Summer Time</dst_tz_full_name>
                      <dst_start>
                          <utc_time>2026-03-29 TIME 01:00</utc_time>
                          <duration>+1.00H</duration>
                          <gap>true</gap>
                          <date_time_after>2026-03-29 TIME 03:00</date_time_after>
                          <date_time_before>2026-03-29 TIME 02:00</date_time_before>
                          <overlap>false</overlap>
                      </dst_start>
                      <dst_end>
                          <utc_time>2026-10-25 TIME 01:00</utc_time>
                          <duration>-1.00H</duration>
                          <gap>false</gap>
                          <date_time_after>2026-10-25 TIME 02:00</date_time_after>
                          <date_time_before>2026-10-25 TIME 03:00</date_time_before>
                          <overlap>true</overlap>
                      </dst_end>
                  </time_zone>
                </LinkedHashMap>

        "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 [email protected]"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at [email protected]"
                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 [email protected]"
                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":
          $ref: "#/components/responses/NotFound"
        "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"

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/timezone/convert:
    get:
      operationId: convertTimezone
      summary: IPGeolocation.io 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:
      - $ref: "#/components/parameters/TzFrom"
      - $ref: "#/components/parameters/TzTo"
      - $ref: "#/components/parameters/LocationFrom"
      - $ref: "#/components/parameters/LocationTo"
      - $ref: "#/components/parameters/LatFrom"
      - $ref: "#/components/parameters/LatTo"
      - $ref: "#/components/parameters/LongFrom"
      - $ref: "#/components/parameters/LongTo"
      - $ref: "#/components/parameters/IataFrom"
      - $ref: "#/components/parameters/IataTo"
      - $ref: "#/components/parameters/IcaoFrom"
      - $ref: "#/components/parameters/IcaoTo"
      - $ref: "#/components/parameters/LocodeFrom"
      - $ref: "#/components/parameters/LocodeTo"
      - $ref: "#/components/parameters/Time"
      - $ref: "#/components/parameters/Output"
      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
            application/xml:
              schema:
                $ref: '#/components/schemas/TimeConversionResponse'
              example: |
                <LinkedHashMap>
                  <original_time>2026-03-16 21:43:44</original_time>
                  <converted_time>2026-03-16 22:43:44</converted_time>
                  <diff_hour>1</diff_hour>
                  <diff_min>60</diff_min>
                </LinkedHashMap>
        "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 [email protected]."
                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 [email protected]."
                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 [email protected]."
                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 [email protected]"
                lockedAccount:
                  summary: Account locked
                  value:
                    message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at [email protected]"
                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 [email protected]"
        "404":
          $ref: "#/components/responses/NotFound"
        "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"

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    NotFound:
      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 ci

# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ipgeolocation/refs/heads/main/openapi/ipgeolocation-timezone-openapi.yml