openapi: 3.0.7 info: title: 'IPGeolocation.io: Abuse Contact ASN Lookup IP Geolocation API' version: '3.0' description: "Retrieve abuse contact information associated with an IPv4 address or IPv6 address.\nThe API returns the organization responsible for handling abuse complaints related\nto the queried IP address, including the abuse contact role, organization name,\nregistered address, email contacts, and phone numbers.\n\nThe abuse contact data helps organizations report malicious activities such as\nspam, phishing, DDoS attacks, IP spoofing, and other network abuse to the\nresponsible network operator.\n\nOne endpoint is available:\n\n- **Abuse lookup** (`GET /v3/abuse`) returns abuse contact information for a\n single IPv4 or IPv6 address per request.\n\nUse query parameters to control which fields are returned and which fields are\nexcluded from the response to reduce payload size when only specific data\nis required.\n\n## Authentication\n\nTwo authentication methods are supported:\n\n### API Key\n\nPass your API key as the `apiKey` query parameter on every request. You can find your\nkey in the [IPGeolocation dashboard](https://app.ipgeolocation.io/). Store it in\nserver-side environment variables. Avoid exposing it in client-side JavaScript.\n\n### Request Origin (CORS)\n\nAvailable on paid plans only. Whitelist your domain in the dashboard under the\n\"API Keys\" section. Once configured, requests from that domain (and all its subdomains)\nare accepted without passing `apiKey`. Enter your root domain (e.g. `example.com`),\nnot the full URL.\n\nEach plan has a limit on the number of extra API keys and request origins:\n\n| Plan | Extra API Keys + Request Origins |\n|---|---|\n| Starter (150K requests) | 1 |\n| Core (250K requests) | 1 |\n| Plus (500K requests) | 2 |\n| Pro (1M requests) | 2 |\n| Business (2M requests) | 3 |\n| Premium (5M requests) | 3 |\n\nAdditional keys or origins can be added for $2.50 per month each.\n\n## Response Formats\n\nThe API supports JSON (default) and XML output.\n\n- Set the `output` query parameter to `json` or `xml`.\n- Alternatively, set the `Accept` header to `application/json`, `application/xml`,\n or `text/xml`.\n\nIf neither is specified, the response is returned as JSON. XML responses use a\n`LinkedHashMap` root element.\n\n## Credit Usage\n\nCredits are charged only for successful **HTTP 200** responses. The exact number of\ncredits consumed by a request is returned in the `X-Credits-Charged` response header.\n\nA **single IP abuse contact lookup** (`GET /v3/abuse`) consumes **1 credit** per request.\n\n\n## Field Filtering\n\nUse `fields` to cherry-pick specific fields, or `excludes` to drop fields you do not\nneed. Both accept dot-notation for nested fields (e.g. `abuse.route`,\n`abuse.organization`). The `ip` field is always present regardless of filters.\n\n## Parameter Name Casing\n\nQuery parameter names are case-sensitive. Use exact names such as\n`apiKey`, `ip`, `fields`, `excludes`, and `output`.\n\n## Plan Availability and Usage Limits\n\nThe IP Abuse Contact API is available **only on paid plans**.\n\nPaid subscriptions do not have fixed daily, hourly, or monthly rate limits. \nIf the monthly quota is exceeded, requests continue and a surcharge may be applied according to the subscribed plan.\n\nFree plans cannot access the IP Abuse Contact API. Requests made with a free plan API key return **HTTP 401 Unauthorized**.\n" 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 servers: - url: https://api.ipgeolocation.io description: Production security: - ApiKeyAuth: [] 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 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: "\n 91.128.103.196\n 91.128.103.196\n \n EU\n Europe\n SE\n SWE\n Sweden\n Kingdom of Sweden\n Stockholm\n Stockholms län\n SE-AB\n Stockholm\n Stockholm\n Stockholm\n 8.793\n high\n \n 164 40\n 59.40510\n 17.95510\n true\n https://ipgeolocation.io/static/flags/se_64.png\n 9972319\n \U0001F1F8\U0001F1EA\n \n \n +46\n .se\n sv-SE\n se\n sma\n fi-SE\n \n \n \n 91.128.0.0/14\n false\n \n \n SEK\n Swedish Krona\n kr\n \n \n AS1257\n Tele2 Sverige AB\n SE\n ISP\n tele2.com\n 2002-09-19\n RIPE\n \n \n Tele2 Sverige AB\n ISP\n tele2.com\n \n \n 0\n false\n false\n 0\n \n false\n false\n 0\n \n false\n \n false\n false\n false\n false\n false\n \n \n \n 91.128.0.0/14\n SE\n Swipnet Staff\n \n group\n
Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN
\n abuse@tele2.com\n +46 8 5626 42 10\n \n \n Europe/Stockholm\n 1\n 1\n 2026-03-02 13:32:39.256+0100\n 1772454759.256\n CET\n Central European Standard Time\n CET\n Central European Standard Time\n false\n 0\n true\n CEST\n Central European Summer Time\n \n 2026-03-29 TIME 01:00\n +1.00H\n true\n 2026-03-29 TIME 03:00\n 2026-03-29 TIME 02:00\n false\n \n \n 2026-10-25 TIME 01:00\n -1.00H\n false\n 2026-10-25 TIME 02:00\n 2026-10-25 TIME 03:00\n true\n \n \n \n PostmanRuntime/7.49.1\n PostmanRuntime\n Robot\n 7.49.1\n 7\n \n Postman Runtime\n Robot\n Postman\n Unknown\n \n \n PostmanRuntime\n Robot\n 7.49.1\n 7\n \n \n Cloud\n Cloud\n ??\n ??\n ??\n \n \n\n" freeMinimalResponse: summary: Free plan default response (XML) value: "\n 165.227.0.0\n \n NA\n North America\n US\n USA\n United States\n United States of America\n Washington, D.C.\n California\n US-CA\n Santa Clara County\n Santa Clara\n 95051\n 37.35983\n -121.98144\n false\n https://ipgeolocation.io/static/flags/us_64.png\n 5346804\n \U0001F1FA\U0001F1F8\n \n \n +1\n .us\n en-US\n es-US\n haw\n fr\n \n \n USD\n US Dollar\n $\n \n \n AS14061\n DigitalOcean, LLC\n US\n \n \n America/Los_Angeles\n -8\n -8\n 2026-03-02 03:29:55.186-0800\n 1772450995.186\n PST\n Pacific Standard Time\n PST\n Pacific Standard Time\n false\n 0\n true\n PDT\n Pacific Daylight Time\n \n 2026-03-08 TIME 10:00\n +1.00H\n true\n 2026-03-08 TIME 03:00\n 2026-03-08 TIME 02:00\n false\n \n \n 2026-11-01 TIME 09:00\n -1.00H\n false\n 2026-11-01 TIME 01:00\n 2026-11-01 TIME 02:00\n true\n \n \n\n" '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: "\n \n 85.219.46.79\n \n EU\n Europe\n ES\n ESP\n Spain\n Kingdom of Spain\n Madrid\n Navarre\n ES-NC\n Provincia de Navarra\n Segundo Ensanche\n 31002\n 42.81253\n -1.64577\n true\n https://ipgeolocation.io/static/flags/es_64.png\n 6359749\n \U0001F1EA\U0001F1F8\n \n \n +34\n .es\n es-ES\n ca\n gl\n eu\n oc\n \n \n \n 85.219.0.0/17\n false\n \n \n EUR\n Euro\n €\n \n \n AS6739\n VODAFONE ONO, S.A.\n ES\n ISP\n corp.vodafone.es\n 2002-01-09\n RIPE\n \n \n ONO HFC\n \n \n \n \n Europe/Madrid\n 1\n 1\n 2026-03-03 19:39:41.143+0100\n 1772563181.143\n CET\n Central European Standard Time\n CET\n Central European Standard Time\n false\n 0\n true\n CEST\n Central European Summer Time\n \n 2026-03-29 TIME 01:00\n +1.00H\n true\n 2026-03-29 TIME 03:00\n 2026-03-29 TIME 02:00\n false\n \n \n 2026-10-25 TIME 01:00\n -1.00H\n false\n 2026-10-25 TIME 02:00\n 2026-10-25 TIME 03:00\n true\n \n \n \n \n '10.0.0.0' is a bogon IP address.\n \n\n" '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: schemas: 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' 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' 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. 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 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. 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: 🇸🇪 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 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' 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 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' 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' 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 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 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 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: ?? 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. 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 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 responses: BadRequest: description: "Bad request. Returned for one of the following reasons:\n\n- The provided IPv4 address, IPv6 address, or domain name is invalid.\n- Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,\n either in a parameter name or its value (especially in the API key).\n- For the `ipgeo-bulk` endpoint:\n - The request payload is empty or missing.\n - The JSON body is malformed.\n - The `ips` field is missing or the `ips` array is empty.\n - More than 50,000 IP addresses are provided in the request.\n- An invalid or unsupported `lang` parameter is provided.\n" 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 NotFound: description: "Not found. Returned for one of the following reasons:\n\n- A syntactically valid IPv4 or IPv6 address does not exist in the IPGeolocation database.\n- An IPv4 address, IPv6 address, or domain name is passed as a path variable\n instead of as a URL query parameter (e.g., using `/v3/ipgeo/8.8.8.8`\n instead of `/v3/ipgeo?ip=8.8.8.8`).\n- A non-existent or incorrect API endpoint is called.\n\nInvalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.\n" 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. 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. 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: "\n \n 413 Request Entity Too Large\n \n \n

413 Request Entity Too Large

\n
nginx/1.24.0 (Ubuntu)
\n \n\n" 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 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.' 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. 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. Unauthorized: description: "Unauthorized. Returned for one of the following reasons:\n\n- The `apiKey` URL parameter is missing.\n- An invalid (random or incorrect) API key is provided.\n- The account has been disabled or locked due to abuse or illegal activity.\n- The API request is made using an API key for a database subscription.\n- The subscription is in a 'paused' state.\n- The subscription trial has expired.\n- The account’s active-until date has passed and renewal or upgrade is required.\n- Any of the following `include` values are used with a Free/Developer plan API key:\n `hostname`, `liveHostname`, `hostnameFallbackLive`, `security`,\n `abuse`, `geo_accuracy`, `dma_code`, or `user_agent`.\n- The bulk IP geolocation endpoint is called using a Free subscription API key.\n- The bulk IP geolocation endpoint is called using Request Origin (CORS)\n authentication. Bulk requests require an `apiKey` and cannot be authenticated\n using Request Origin alone.\n- A domain name lookup is performed using a Free subscription API key.\n- A language other than English is specified in the `lang` parameter\n while using a Free/Developer plan API key.\n" 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. 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. 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 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. TooManyRequests: description: "Too Many Requests. Returned for one of the following reasons:\n\n- The API usage limit has been reached for a Free subscription.\n- The API usage limit has been reached for a Paid subscription with\n status 'past due', 'deleted', or 'trial expired'.\n- The surcharge API usage limit has been reached for the subscribed plan.\n" 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. 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. parameters: 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 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 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: '*' 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 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 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. ' externalDocs: description: IPGeolocation Abuse Contact API documentation url: https://ipgeolocation.io/documentation/ip-abuse-contact-api.html