openapi: 3.0.7 info: title: 'IPGeolocation.io: IPGeolocation API' version: "3.0" description: | Look up geolocation, network, company, ASN, timezone, currency, abuse contact, and security threat data for any IPv4 address, IPv6 address, or domain name. The API also parses User-Agent strings when requested. Two endpoints are available: - **Single lookup** (`GET /v3/ipgeo`) returns data for one IP or domain per request. - **Bulk lookup** (`POST /v3/ipgeo-bulk`) accepts up to 50,000 IPs or domains in a single request. Requires a paid plan. Use query parameters to control which optional modules are included, which fields are returned, and which fields are excluded. Both endpoints share the same query parameters and the same response schema per IP. ## 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. ## Credits Credits are charged only on successful HTTP 200 responses. The exact charge for any request is returned in the `X-Credits-Charged` response header. | Condition | Credits charged | |---|---| | Base lookup (location, ASN, company, network, currency, timezone) | 1 | | Adding `dma_code`, `geo_accuracy`, `hostname`, or `user_agent` | 0 extra (still 1) | | Adding `security` | +2 (total 3) | | Adding `abuse` | +1 (total 2) | | Adding `security` and `abuse` | +3 (total 4) | | `include=*` (everything) | 4 | | Only `security` via `include=security&fields=security` | 2 | | Only `abuse` via `include=abuse&fields=abuse` | 1 | For bulk requests, total credits equal credits per lookup multiplied by the number of valid IPs. Private, bogon, and malformed IPs are not counted as valid and do not consume credits. ## Response Language Pass `lang` to get translated location names. English is the default. Non-English responses require a paid plan. ## Field Filtering Use `fields` to cherry-pick specific fields, or `excludes` to drop fields you do not need. Both accept dot-notation for nested fields (e.g. `location.city`, `security.threat_score`). The `ip` field is always present regardless of filters. ## Parameter Name Casing Query parameter names are case-sensitive. Use exact names such as `apiKey`, `ip`, `include`, `fields`, `excludes`, `lang`, and `output`. ## Rate Limits - **Free plan:** 1,000 requests per day (hard limit). - **Paid plans:** No daily, hourly, or monthly rate limit. If the monthly quota is exceeded, requests continue and a surcharge is added to the monthly bill. ## Free vs. Paid Plan Differences | Capability | Free | Paid | |---|---|---| | IPv4 / IPv6 lookup | Yes | Yes | | Domain lookup | No | Yes | | Bulk lookup (`/v3/ipgeo-bulk`) | No | Yes | | `include` parameter (optional modules) | No | Yes | | `lang` (non-English responses) | No | Yes | | `fields` / `excludes` filtering | Yes | Yes | | `network` object in default response | No | Yes | | `company` object in default response | No | Yes | | Basic `asn` fields (`as_number`, `organization`, `country`) | Yes | Yes | | Extended `asn` fields (`type`, `domain`, `rir`, `date_allocated`) | No | Yes | contact: name: IPGeolocation Support url: https://ipgeolocation.io/contact.html email: support@ipgeolocation.io termsOfService: https://ipgeolocation.io/tos.html license: name: Proprietary url: https://ipgeolocation.io/tos.html externalDocs: description: IPGeolocation IP Location API documentation url: https://ipgeolocation.io/documentation/ip-location-api.html servers: - url: https://api.ipgeolocation.io description: Production security: - ApiKeyAuth: [] paths: /v3/ipgeo: get: operationId: lookupIpGeolocation summary: IPGeolocation.io 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: - $ref: "#/components/parameters/Ip" - $ref: "#/components/parameters/Lang" - $ref: "#/components/parameters/Include" - $ref: "#/components/parameters/Fields" - $ref: "#/components/parameters/Excludes" - $ref: "#/components/parameters/Output" 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: "🇸🇪" 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 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 is_spam: false is_cloud_provider: false cloud_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: "🇺🇸" 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 application/xml: schema: $ref: "#/components/schemas/IpGeolocationResponse" examples: paidFullResponse: summary: Paid plan, all modules included (XML) value: | 91.128.103.196 91.128.103.196 EU Europe SE SWE Sweden Kingdom of Sweden Stockholm Stockholms län SE-AB Stockholm Stockholm Stockholm 8.793 high 164 40 59.40510 17.95510 true https://ipgeolocation.io/static/flags/se_64.png 9972319 🇸🇪 +46 .se sv-SE se sma fi-SE 91.128.0.0/14 false SEK Swedish Krona kr AS1257 Tele2 Sverige AB SE ISP tele2.com 2002-09-19 RIPE Tele2 Sverige AB ISP tele2.com 0 false false 0 false false 0 false false false false false false 91.128.0.0/14 SE Swipnet Staff group
Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN
abuse@tele2.com +46 8 5626 42 10 Europe/Stockholm 1 1 2026-03-02 13:32:39.256+0100 1772454759.256 CET Central European Standard Time CET Central European Standard Time false 0 true CEST Central European Summer Time 2026-03-29 TIME 01:00 +1.00H true 2026-03-29 TIME 03:00 2026-03-29 TIME 02:00 false 2026-10-25 TIME 01:00 -1.00H false 2026-10-25 TIME 02:00 2026-10-25 TIME 03:00 true PostmanRuntime/7.49.1 PostmanRuntime Robot 7.49.1 7 Postman Runtime Robot Postman Unknown PostmanRuntime Robot 7.49.1 7 Cloud Cloud ?? ?? ?? freeMinimalResponse: summary: Free plan default response (XML) value: | 165.227.0.0 NA North America US USA United States United States of America Washington, D.C. California US-CA Santa Clara County Santa Clara 95051 37.35983 -121.98144 false https://ipgeolocation.io/static/flags/us_64.png 5346804 🇺🇸 +1 .us en-US es-US haw fr USD US Dollar $ AS14061 DigitalOcean, LLC US America/Los_Angeles -8 -8 2026-03-02 03:29:55.186-0800 1772450995.186 PST Pacific Standard Time PST Pacific Standard Time false 0 true PDT Pacific Daylight Time 2026-03-08 TIME 10:00 +1.00H true 2026-03-08 TIME 03:00 2026-03-08 TIME 02:00 false 2026-11-01 TIME 09:00 -1.00H false 2026-11-01 TIME 01:00 2026-11-01 TIME 02:00 true "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "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/ipgeo-bulk: post: operationId: bulkLookupIpGeolocation summary: IPGeolocation.io 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: - $ref: "#/components/parameters/Lang" - $ref: "#/components/parameters/Include" - $ref: "#/components/parameters/Fields" - $ref: "#/components/parameters/Excludes" - $ref: "#/components/parameters/Output" 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: "🇺🇸" 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 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." application/xml: schema: type: array xml: name: ArrayList wrapped: true items: $ref: "#/components/schemas/BulkGeolocationResponseItem" xml: name: item examples: bulkResponse: summary: Bulk response with one valid and one error entry (XML) value: | 85.219.46.79 EU Europe ES ESP Spain Kingdom of Spain Madrid Navarre ES-NC Provincia de Navarra Segundo Ensanche 31002 42.81253 -1.64577 true https://ipgeolocation.io/static/flags/es_64.png 6359749 🇪🇸 +34 .es es-ES ca gl eu oc 85.219.0.0/17 false EUR Euro € AS6739 VODAFONE ONO, S.A. ES ISP corp.vodafone.es 2002-01-09 RIPE ONO HFC Europe/Madrid 1 1 2026-03-03 19:39:41.143+0100 1772563181.143 CET Central European Standard Time CET Central European Standard Time false 0 true CEST Central European Summer Time 2026-03-29 TIME 01:00 +1.00H true 2026-03-29 TIME 03:00 2026-03-29 TIME 02:00 false 2026-10-25 TIME 01:00 -1.00H false 2026-10-25 TIME 02:00 2026-10-25 TIME 03:00 true '10.0.0.0' is a bogon IP address. "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "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" x-microcks-operation: delay: 0 dispatcher: FALLBACK components: parameters: Ip: 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 examples: ipv4: summary: IPv4 address value: "91.128.103.196" ipv6: summary: IPv6 address value: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c" domain: summary: Domain name (paid plans only) value: "ipgeolocation.io" Lang: 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. schema: type: string default: "en" enum: - en - de - ru - ja - fr - cn - es - cs - it - ko - fa - pt Include: 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. **Available values:** | Value | What it adds | Extra credits | |---|---|---| | `geo_accuracy` | `location.locality`, `location.accuracy_radius`, `location.confidence` | 0 | | `dma_code` | `location.dma_code` (US IPs only) | 0 | | `user_agent` | `user_agent` object (parses the `User-Agent` header) | 0 | | `security` | `security` object with threat signals | +2 | | `abuse` | `abuse` object with abuse contact info | +1 | | `hostname` | `hostname` field (from local database, fast, experimental) | 0 | | `liveHostname` | `hostname` field (live DNS lookup, slower, accurate) | 0 | | `hostnameFallbackLive` | `hostname` field (local first, falls back to live) | 0 | | `*` | All of the above | +3 | 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 examples: none: summary: Do not include any optional modules value: "" security: summary: Include security threat data value: "security" multiple: summary: Include security and abuse data value: "security,abuse" allNonBillable: summary: Include all free modules value: "dma_code,geo_accuracy,hostname,user_agent" all: summary: Include everything value: "*" Fields: 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 examples: none: summary: Return the full response (no field filtering) value: "" locationOnly: summary: Return only the location object value: "location" nestedFields: summary: Return specific nested fields value: "location.country_name,asn.organization" securityFields: summary: Return specific security fields (requires include=security) value: "location.city,security.threat_score,security.is_vpn" Excludes: 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 examples: none: summary: Do not exclude any fields value: "" excludeObjects: summary: Exclude entire objects and a nested field value: "location.continent_code,currency,company.type" Output: 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. schema: type: string enum: [json, xml] default: json responses: BadRequest: 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" Unauthorized: 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." NotFound: 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/ipgeo-invalid." 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: | 413 Request Entity Too Large

413 Request Entity Too Large

nginx/1.24.0 (Ubuntu)
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 usage limit has been reached for a Free subscription. - The API usage limit has been reached for a Paid subscription with status 'past due', 'deleted', or 'trial expired'. - The surcharge API usage limit has been reached for the subscribed plan. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: usageLimitReached: summary: API usage limit reached value: message: "You have exceeded the limit of PLAN_USAGE_LIMIT requests per PLAN_INERVAL for your subscribed PLAN plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation API without interruption." surchargeLimitReached: summary: Surcharge usage limit reached value: message: "You have reached the surcharge amount limit of PLAN_USAGE_LIMIT_AND_SURCHARGE_LIMIT on your subscribed PLAN plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation API without interruption." ClientClosedRequest: description: | The client closed the connection before the server finished processing the request. 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." 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." 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 examples: - "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`. 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/Location" country_metadata: $ref: "#/components/schemas/CountryMetadata" network: $ref: "#/components/schemas/Network" currency: $ref: "#/components/schemas/Currency" asn: $ref: "#/components/schemas/Asn" company: $ref: "#/components/schemas/Company" security: $ref: "#/components/schemas/Security" abuse: $ref: "#/components/schemas/Abuse" time_zone: $ref: "#/components/schemas/TimeZone" user_agent: $ref: "#/components/schemas/UserAgent" 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/Location" country_metadata: $ref: "#/components/schemas/CountryMetadata" network: $ref: "#/components/schemas/Network" currency: $ref: "#/components/schemas/Currency" asn: $ref: "#/components/schemas/Asn" company: $ref: "#/components/schemas/Company" security: $ref: "#/components/schemas/Security" abuse: $ref: "#/components/schemas/Abuse" time_zone: $ref: "#/components/schemas/TimeZone" user_agent: $ref: "#/components/schemas/UserAgent" Location: 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: "🇸🇪" CountryMetadata: 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 examples: - "sv-SE" - "se" - "sma" - "fi-SE" Network: 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 Currency: 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" Asn: 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" Company: 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" Security: 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 examples: - "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 examples: - "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 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." Abuse: 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 examples: - "abuse@tele2.com" phone_numbers: type: array description: Phone numbers for the abuse contact. items: type: string examples: - "+46 8 5626 42 10" TimeZone: 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/DstTransition" - 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/DstTransition" - type: object maxProperties: 0 DstTransition: 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 UserAgent: 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/UserAgentDevice" engine: $ref: "#/components/schemas/UserAgentEngine" operating_system: $ref: "#/components/schemas/UserAgentOperatingSystem" UserAgentDevice: 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" UserAgentEngine: 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" UserAgentOperatingSystem: 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: "??" 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. 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. externalDocs: description: IPGeolocation API documentation and integration guides url: https://ipgeolocation.io/documentation/ip-location-api.html