openapi: 3.0.4
info:
title: 'IPGeolocation.io'
version: "3.0"
description: |
Combined OpenAPI specification for all IPGeolocation.io APIs.
Includes IP Geolocation, IP Security, ASN Lookup, Abuse Contact,
Astronomy, Timezone, and User Agent endpoints.
## API Overview
This collection covers the following API groups:
- **IP Geolocation**: Single and bulk IP/domain geolocation lookups
- **IP Security**: VPN, proxy, Tor, bot, and threat intelligence
- **ASN Lookup**: Autonomous System Number metadata and routing data
- **IP Abuse Contact**: Registry-based abuse contact information
- **Timezone**: Timezone lookup and time conversion
- **User Agent**: Parse browser, device, and OS from User-Agent strings
- **Astronomy**: Sunrise/sunset, moon phase, and astronomical data
All endpoints are available at `https://api.ipgeolocation.io` and require an API key passed as the `apiKey` query parameter.
Full documentation: https://ipgeolocation.io/documentation
## Billing & Credits
Billing is based on API credits, not requests. Credits are charged only on successful HTTP 200 responses; the exact charge for a request is returned in the `X-Credits-Charged` response header.
- **Free plan:** 1,000 credits per day (hard limit — no overage).
- **Paid plans:** No rate limits. Each billing period includes a fixed credit allowance (Starter 150,000/month, Plus 500,000/month, Pro 1,000,000/month, Business 2,000,000/month, Premium 5,000,000/month). After the allowance is exhausted, requests keep succeeding only while overage (surcharge) is enabled and within its limit; otherwise the API returns HTTP 429.
Credit cost per successful request: IP geolocation base lookup 1 credit (adding `security` +2, adding `abuse` +1, `include=*` → 4 credits); IP Security 2; Abuse Contact 1; ASN 1; Timezone 1; User-Agent 1; Astronomy 1.
Each plan has a limit on the number of extra API keys and request origins:
| Plan | Extra API Keys + Request Origins |
|---|---|
| Free | 0 |
| Starter | 1 |
| Plus | 2 |
| Pro | 2 |
| Business | 3 |
| Premium | 3 |
Additional keys or origins can be added for $2.50 per month each.
Credits & usage: https://ipgeolocation.io/documentation/credits-usage.html
Pricing: https://ipgeolocation.io/pricing.html
servers:
- url: https://api.ipgeolocation.io
description: IPGeolocation.io production server
tags:
- name: IP Geolocation
description: |
IP geolocation API endpoints for looking up geographic location, network routing,
ASN ownership, company attribution, timezone, currency, security threat intelligence,
abuse contact, and User-Agent data. Accepts IPv4 addresses, IPv6 addresses, and
domain names. The single lookup endpoint (`GET /v3/ipgeo`) resolves one IP or domain
per request. The bulk lookup endpoint (`POST /v3/ipgeo-bulk`) accepts up to 50,000
entries per request and requires a paid plan.
- name: IP Security
description: |
IP security intelligence endpoints used to detect VPNs,
proxies, Tor exit nodes, relay networks, bot activity,
spam activity, cloud providers, and other anonymization
technologies associated with IP addresses.
The single lookup endpoint (`GET /v3/security`) analyzes
one IP per request.
The bulk lookup endpoint (`POST /v3/security-bulk`)
accepts up to 50,000 IP addresses per request.
- name: ASN Lookup
description: |
API endpoint for retrieving Autonomous System Number (ASN) information
associated with IPv4 addresses, IPv6 addresses, or specific ASN numbers.
The response includes ASN metadata such as the ASN number, organization
name, country of registration, ASN type, domain, allocation details,
routing statistics, and the Regional Internet Registry (RIR) responsible
for the allocation.
Additional routing intelligence such as peers, upstreams, downstreams,
announced routes, and raw WHOIS registry data can also be retrieved
using the `include` parameter.
This information helps analyze internet routing, identify network
operators, and understand how Autonomous Systems interconnect
across the internet.
- name: IP Abuse Contact
description: |
API endpoint for retrieving abuse contact information associated
with IPv4 and IPv6 addresses. The response contains registry-based
contact details for reporting malicious or abusive network activity
such as spam, phishing, DDoS attacks, or unauthorized access attempts.
- name: Timezone
description: |
API endpoints for retrieving current date, time, and timezone
information for a given input such as an IANA timezone identifier,
geographic coordinates, location address, IPv4 or IPv6 address,
airport codes (IATA or ICAO), or UN/LOCODE.
The API can also convert timestamps between different timezones,
locations, coordinates, airports, or UN/LOCODE identifiers.
Responses include detailed timezone metadata such as UTC offset,
daylight saving time (DST) status, formatted timestamps, and
upcoming DST transition information. Depending on the lookup
method used, the response may also include geolocation data,
airport details, or city information.
- name: User Agent
description: |
API endpoints for parsing user agent strings into browser, device, layout engine,
and operating system details. Supports single lookups via request header, custom
string lookups via JSON body, and bulk parsing of up to 50,000 strings per request.
Also detects bots, crawlers, and malicious or malformed user agent strings.
- name: Astronomy
description: |
API endpoints for retrieving astronomical information for a given
location, including sunrise and sunset times, moonrise and moonset
times, twilight phases, golden hour and blue hour windows, solar noon,
sun and moon position data (altitude, azimuth, distance), and moon
phase.
A time series endpoint is also available to retrieve daily astronomical
data across a date range of up to 90 days.
paths:
/v3/ipgeo:
get:
operationId: lookupIpGeolocation
security:
- ApiKeyAuth: []
summary: Single IP Geolocation Lookup
description: |
Returns geolocation and enrichment data for a single IPv4 address, IPv6 address,
or domain name. When `ip` is omitted, the API resolves the caller's public IP
automatically, which is useful for client-side lookups.
The base response always includes `location`, `country_metadata`, `currency`,
`asn`, and `time_zone`. Paid plans also get `network` and `company` by default.
Use the `include` parameter to add optional modules such as `security`, `abuse`,
`user_agent`, `geo_accuracy`, `dma_code`, and hostname resolution.
Use `fields` and `excludes` to control exactly which parts of the response you
receive. This reduces payload size and can improve response times.
tags:
- IP Geolocation
parameters:
- name: ip
in: query
required: false
description: |
An IPv4 address, IPv6 address, or domain name to look up. When omitted, the API
resolves the public IP of the requesting client. Empty or whitespace-only values
are treated the same as omission and resolve caller IP. Domain lookups require a
paid plan. Pass `ip` only once. If multiple `ip` query parameters are sent,
values may be merged and treated as invalid input (HTTP 400).
schema:
type: string
example: "165.227.0.0"
- name: lang
in: query
required: false
description: |
Language code for translated location names. Defaults to `en`. Non-English
responses require a paid plan. Free plans always receive English regardless
of this parameter. Unsupported `lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`. Defaults to `en`.
schema:
type: string
default: "en"
- name: include
in: query
required: false
description: |
Comma-separated list of optional data modules to add to the response. These are
not returned by default. Requires a paid plan.
If multiple hostname options are passed in `include`, hostname resolution uses
this precedence order: `liveHostname` first, then `hostname`, then
`hostnameFallbackLive`.
If none is specified, the `hostname` field is not returned.
For `user_agent`, the API parses the `User-Agent` header from the request. For
server-side calls, forward your visitor's User-Agent string in the header so the
parsed result matches the actual visitor.
For additional query parameters (`include`, `fields`, `excludes`, `output`),
unknown values are ignored. The API still returns HTTP 200 and applies only
recognized values.
Free plan behavior for `include=*`: the API returns HTTP 200 and ignores the
include request, returning only base response fields. In contrast, specific
include values such as `include=security` return HTTP 401 on free plans.
schema:
type: string
example: "*"
- name: fields
in: query
required: false
description: |
Comma-separated list of fields or objects to return. Everything else is omitted.
The `ip` field is always returned regardless of this filter.
Supports dot-notation for nested fields: `location.city`, `asn.organization`.
To return an entire object, use the object key: `location`, `security`.
If a field belongs to an optional module (e.g. `security.threat_score`), you
must also pass the corresponding `include` value.
If you omit `include`, the request still succeeds, but fields from optional
modules are not returned.
If the same field or object is specified in both `fields` and `excludes`, the
object is still returned, but it will be empty.
If the same field or object is specified in `include`, `fields`, and `excludes`,
`include` takes priority over both `fields` and `excludes`.
If you list both an object key and one of its nested fields separated by comma
(e.g. `security,security.threat_score`), the full object is returned.
Unknown field paths are ignored. The API still returns HTTP 200.
Available on all plans including Free.
schema:
type: string
example: "location.city,security.threat_score,security.is_vpn"
- name: excludes
in: query
required: false
description: |
Comma-separated list of fields or objects to remove from the response. The `ip`
field cannot be excluded.
Supports dot-notation for nested fields: `location.continent_code`.
To exclude an entire object, use the object key: `currency`, `time_zone`.
If the same field or object is specified in both `fields` and `excludes`, the
object is still returned, but it will be empty.
If the same field or object is specified in `include`, `fields`, and `excludes`,
`include` takes priority over both `fields` and `excludes`.
Unknown fields or object keys in `excludes` are ignored. The API still returns
HTTP 200.
Available on all plans including Free.
schema:
type: string
example: "location.continent_code,currency,company.type"
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
responses:
"200":
description: Geolocation data for the requested IP or domain.
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: "#/components/schemas/IpGeolocationResponse"
examples:
paidFullResponse:
summary: Paid plan, all modules included
value:
ip: "91.128.103.196"
hostname: "91.128.103.196"
location:
continent_code: "EU"
continent_name: "Europe"
country_code2: "SE"
country_code3: "SWE"
country_name: "Sweden"
country_name_official: "Kingdom of Sweden"
country_capital: "Stockholm"
state_prov: "Stockholms län"
state_code: "SE-AB"
district: "Stockholm"
city: "Stockholm"
locality: "Stockholm"
accuracy_radius: "4.395"
confidence: "high"
dma_code: ""
zipcode: "164 40"
latitude: "59.40510"
longitude: "17.95510"
is_eu: true
country_flag: "https://ipgeolocation.io/static/flags/se_64.png"
geoname_id: "9972319"
country_emoji: "\U0001F1F8\U0001F1EA"
country_metadata:
calling_code: "+46"
tld: ".se"
languages:
- "sv-SE"
- "se"
- "sma"
- "fi-SE"
network:
connection_type: ""
route: "91.128.0.0/14"
is_anycast: false
is_cdn: false
cdn_provider_name: ""
currency:
code: "SEK"
name: "Swedish Krona"
symbol: "kr"
asn:
as_number: "AS1257"
organization: "Tele2 Sverige AB"
country: "SE"
type: "ISP"
domain: "tele2.com"
date_allocated: "2024-12-13"
rir: "RIPE"
company:
name: "Tele2 Sverige AB"
type: "ISP"
domain: "tele2.com"
security:
threat_score: 0
is_tor: false
is_proxy: false
proxy_provider_names: []
proxy_confidence_score: 0
proxy_last_seen: ""
is_residential_proxy: false
is_vpn: false
vpn_provider_names: []
vpn_confidence_score: 0
vpn_last_seen: ""
is_relay: false
relay_provider_name: ""
is_anonymous: false
is_known_attacker: false
is_bot: false
bot_confidence_score: 0
bot_operator_name: ""
bot_type: ""
is_known_good_bot: false
bot_last_seen: ""
is_spam: false
is_cloud_provider: false
cloud_provider_name: ""
is_corporate_gateway: false
corporate_gateway_type: ""
corporate_gateway_provider_name: ""
abuse:
route: "91.128.0.0/14"
country: "SE"
name: "Swipnet Staff"
organization: ""
kind: "group"
address: "Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN"
emails:
- "abuse@tele2.com"
phone_numbers:
- "+46 8 5626 42 10"
time_zone:
name: "Europe/Stockholm"
offset: 1
offset_with_dst: 1
current_time: "2026-02-13 09:19:24.410+0100"
current_time_unix: 1770970764.41
current_tz_abbreviation: "CET"
current_tz_full_name: "Central European Standard Time"
standard_tz_abbreviation: "CET"
standard_tz_full_name: "Central European Standard Time"
is_dst: false
dst_savings: 0
dst_exists: true
dst_tz_abbreviation: "CEST"
dst_tz_full_name: "Central European Summer Time"
dst_start:
utc_time: "2026-03-29 TIME 01:00"
duration: "+1.00H"
gap: true
date_time_after: "2026-03-29 TIME 03:00"
date_time_before: "2026-03-29 TIME 02:00"
overlap: false
dst_end:
utc_time: "2026-10-25 TIME 01:00"
duration: "-1.00H"
gap: false
date_time_after: "2026-10-25 TIME 02:00"
date_time_before: "2026-10-25 TIME 03:00"
overlap: true
user_agent:
user_agent_string: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0"
name: "Edge"
type: "Browser"
version: "143"
version_major: "143"
device:
name: "Linux Desktop"
type: "Desktop"
brand: "Unknown"
cpu: "Intel x86_64"
engine:
name: "Blink"
type: "Browser"
version: "143"
version_major: "143"
operating_system:
name: "Linux"
type: "Desktop"
version: "??"
version_major: "??"
build: "??"
freeMinimalResponse:
summary: Free plan default response
value:
ip: "165.227.0.0"
location:
continent_code: "NA"
continent_name: "North America"
country_code2: "US"
country_code3: "USA"
country_name: "United States"
country_name_official: "United States of America"
country_capital: "Washington, D.C."
state_prov: "California"
state_code: "US-CA"
district: "Santa Clara County"
city: "Santa Clara"
zipcode: "95051"
latitude: "37.35983"
longitude: "-121.98144"
is_eu: false
country_flag: "https://ipgeolocation.io/static/flags/us_64.png"
geoname_id: "5346804"
country_emoji: "\U0001F1FA\U0001F1F8"
country_metadata:
calling_code: "+1"
tld: ".us"
languages:
- "en-US"
- "es-US"
- "haw"
- "fr"
currency:
code: "USD"
name: "US Dollar"
symbol: "$"
asn:
as_number: "AS14061"
organization: "DigitalOcean, LLC"
country: "US"
time_zone:
name: "America/Los_Angeles"
offset: -8
offset_with_dst: -8
current_time: "2026-02-09 09:54:51.206-0800"
current_time_unix: 1770659691.206
current_tz_abbreviation: "PST"
current_tz_full_name: "Pacific Standard Time"
standard_tz_abbreviation: "PST"
standard_tz_full_name: "Pacific Standard Time"
is_dst: false
dst_savings: 0
dst_exists: true
dst_tz_abbreviation: "PDT"
dst_tz_full_name: "Pacific Daylight Time"
dst_start:
utc_time: "2026-03-08 TIME 10:00"
duration: "+1.00H"
gap: true
date_time_after: "2026-03-08 TIME 03:00"
date_time_before: "2026-03-08 TIME 02:00"
overlap: false
dst_end:
utc_time: "2026-11-01 TIME 09:00"
duration: "-1.00H"
gap: false
date_time_after: "2026-11-01 TIME 01:00"
date_time_before: "2026-11-01 TIME 02:00"
overlap: true
"400":
description: |
Bad request. Returned for one of the following reasons:
- The provided IPv4 address, IPv6 address, or domain name is invalid.
- Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,
either in a parameter name or its value (especially in the API key).
- For the `ipgeo-bulk` endpoint:
- The request payload is empty or missing.
- The JSON body is malformed.
- The `ips` field is missing or the `ips` array is empty.
- More than 50,000 IP addresses are provided in the request.
- An invalid or unsupported `lang` parameter is provided.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
invalidIp:
summary: Invalid IPv4/IPv6/domain input
value:
message: "Provided name, service or IP address '999.999.999.999' is not valid."
specialCharacters:
summary: Special characters in API URL or key
value:
message: "Invalid character found in the request target."
malformedJson:
summary: Malformed JSON body for bulk endpoint
value:
message: "Malformed JSON request or invalid field"
missingIps:
summary: Bulk body missing ips field
value:
message: "IP addresses for bulk lookup are missing"
emptyBulkIps:
summary: Bulk ips array is empty
value:
message: "'ips' must not be empty or null"
tooManyBulkEntries:
summary: Bulk body exceeds 50,000 entries
value:
message: "No. of lookup queries cannot be more than 50000"
invalidLang:
summary: Unsupported lang parameter value
value:
message: "This 'zz' lang is not valid. Please use 'en' as the default language"
"401":
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing.
- An invalid (random or incorrect) API key is provided.
- The account has been disabled or locked due to abuse or illegal activity.
- The API request is made using an API key for a database subscription.
- The subscription is in a 'paused' state.
- The subscription trial has expired.
- The account’s active-until date has passed and renewal or upgrade is required.
- Any of the following `include` values are used with a Free/Developer plan API key:
`hostname`, `liveHostname`, `hostnameFallbackLive`, `security`,
`abuse`, `geo_accuracy`, `dma_code`, or `user_agent`.
- The bulk IP geolocation endpoint is called using a Free subscription API key.
- The bulk IP geolocation endpoint is called using Request Origin (CORS)
authentication. Bulk requests require an `apiKey` and cannot be authenticated
using Request Origin alone.
- A domain name lookup is performed using a Free subscription API key.
- A language other than English is specified in the `lang` parameter
while using a Free/Developer plan API key.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscriptionKey:
summary: Database subscription API key used for REST API
value:
message: "You cannot query IPGeolocation API on a database plan subscription. "
pausedSubscription:
summary: Subscription is paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired or trial ended
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
freePlanBulk:
summary: Free plan used for bulk endpoint
value:
message: "Bulk IP to geolocation lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
requestOriginBulk:
summary: Bulk endpoint called using Request Origin authentication
value:
message: "Bulk queries are not allowed with request origins. Please use an API key to perform bulk queries."
freePlanInclude:
summary: Free plan used with restricted include parameter
value:
message: "This feature is not supported on your subscription. This feature is available on Paid subscriptions only."
freePlanDomain:
summary: Free plan used with domain lookup
value:
message: "IP to geolocation lookup for domain or service name is not supported on your current subscription. This feature is available to all paid subscriptions only."
freePlanLang:
summary: Free plan used with non-English lang value
value:
message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
"404":
description: |
Not found. Returned for one of the following reasons:
- A syntactically valid IPv4 or IPv6 address does not exist in the IPGeolocation database.
- An IPv4 address, IPv6 address, or domain name is passed as a path variable
instead of as a URL query parameter (e.g., using `/v3/ipgeo/8.8.8.8`
instead of `/v3/ipgeo?ip=8.8.8.8`).
- A non-existent or incorrect API endpoint is called.
Invalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
ipNotInDatabase:
summary: IPv4/IPv6 not found in database
value:
message: "Provided IP Address '8.8.8.8' doesn't exist in our database."
ipAsPathVariable:
summary: IP passed as path variable instead of query parameter
value:
message: "No endpoint GET /v3/ipgeo/8.8.8.8."
wrongEndpoint:
summary: Incorrect or non-existent endpoint
value:
message: "No endpoint GET /v3/security-invalid."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/ipgeo-bulk:
post:
operationId: bulkLookupIpGeolocation
security:
- ApiKeyAuth: []
summary: Bulk IP Geolocation Lookup
description: |
Returns geolocation and enrichment data for up to 50,000 IPv4 addresses, IPv6
addresses, or domain names in a single request. The request body must be a JSON
object with an `ips` array.
This endpoint requires a paid plan. Calling it with a free
plan API key returns HTTP 401.
The response is a JSON array with one element per IP in the request. Each element
is either a full geolocation response object or an error object with only a
`message` field. Invalid, bogon, and unresolvable entries appear as error
objects. Invalid, private, and bogon IPs are not billed.
This endpoint supports the same query parameters as the single lookup endpoint,
including `lang`, `include`, `fields`, `excludes`, and `output`.
Credits are calculated as: credits per lookup multiplied by the number of valid
IPs in the request. The total is returned in the `X-Credits-Charged` response
header. When at least one submitted ip is invalid, the `X-Successful-Record`
response header indicates how many entries were successfully resolved.
Only the `POST` method is accepted. Sending a `GET` request returns HTTP 405.
tags:
- IP Geolocation
parameters:
- name: lang
in: query
required: false
description: |
Language code for translated location names. Defaults to `en`. Non-English
responses require a paid plan. Free plans always receive English regardless
of this parameter. Unsupported `lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`. Defaults to `en`.
schema:
type: string
default: "en"
- name: include
in: query
required: false
description: |
Comma-separated list of optional data modules to add to the response. These are
not returned by default. Requires a paid plan.
If multiple hostname options are passed in `include`, hostname resolution uses
this precedence order: `liveHostname` first, then `hostname`, then
`hostnameFallbackLive`.
If none is specified, the `hostname` field is not returned.
For `user_agent`, the API parses the `User-Agent` header from the request. For
server-side calls, forward your visitor's User-Agent string in the header so the
parsed result matches the actual visitor.
For additional query parameters (`include`, `fields`, `excludes`, `output`),
unknown values are ignored. The API still returns HTTP 200 and applies only
recognized values.
Free plan behavior for `include=*`: the API returns HTTP 200 and ignores the
include request, returning only base response fields. In contrast, specific
include values such as `include=security` return HTTP 401 on free plans.
schema:
type: string
example: "*"
- name: fields
in: query
required: false
description: |
Comma-separated list of fields or objects to return. Everything else is omitted.
The `ip` field is always returned regardless of this filter.
Supports dot-notation for nested fields: `location.city`, `asn.organization`.
To return an entire object, use the object key: `location`, `security`.
If a field belongs to an optional module (e.g. `security.threat_score`), you
must also pass the corresponding `include` value.
If you omit `include`, the request still succeeds, but fields from optional
modules are not returned.
If the same field or object is specified in both `fields` and `excludes`, the
object is still returned, but it will be empty.
If the same field or object is specified in `include`, `fields`, and `excludes`,
`include` takes priority over both `fields` and `excludes`.
If you list both an object key and one of its nested fields separated by comma
(e.g. `security,security.threat_score`), the full object is returned.
Unknown field paths are ignored. The API still returns HTTP 200.
Available on all plans including Free.
schema:
type: string
example: "location.city,security.threat_score,security.is_vpn"
- name: excludes
in: query
required: false
description: |
Comma-separated list of fields or objects to remove from the response. The `ip`
field cannot be excluded.
Supports dot-notation for nested fields: `location.continent_code`.
To exclude an entire object, use the object key: `currency`, `time_zone`.
If the same field or object is specified in both `fields` and `excludes`, the
object is still returned, but it will be empty.
If the same field or object is specified in `include`, `fields`, and `excludes`,
`include` takes priority over both `fields` and `excludes`.
Unknown fields or object keys in `excludes` are ignored. The API still returns
HTTP 200.
Available on all plans including Free.
schema:
type: string
example: "location.continent_code,currency,company.type"
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
requestBody:
required: true
description: |
A JSON object containing an `ips` array. Each element is a string representing
an IPv4 address, IPv6 address, or domain name. The array must not be empty and
must not contain more than 50,000 entries.
content:
application/json:
schema:
$ref: "#/components/schemas/BulkGeolocationRequest"
examples:
mixedIps:
summary: Mixed IPv4, IPv6, and domain
value:
ips:
- "8.8.8.8"
- "91.128.103.196"
- "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
- "ipgeolocation.io"
ipv4Only:
summary: Multiple IPv4 addresses
value:
ips:
- "8.8.8.8"
- "8.8.4.4"
- "165.227.0.0"
responses:
"200":
description: |
An array of results, one per input entry. Valid entries return full
geolocation objects. Invalid, bogon, and unresolvable entries return
objects with only a `message` field.
`X-Successful-Record` is returned only when at least one submitted entry
fails and the number of successful lookups is lower than the number of
submitted entries.
headers:
X-Credits-Charged:
description: |
Total number of API credits consumed. Equals credits per lookup
multiplied by the count of valid IPs.
schema:
type: number
example: 3
X-Successful-Record:
description: |
Number of valid IP addresses or domains that were successfully resolved in
this bulk request. Invalid, bogon, and private IPs are not counted.
This header is included only when at least one bulk entry returns an
error message and total successful lookups are fewer than submitted
entries.
schema:
type: number
example: 4
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/BulkGeolocationResponseItem"
examples:
bulkResponse:
summary: Bulk response with one valid and one error entry
value:
- ip: "8.8.8.8"
location:
continent_code: "NA"
continent_name: "North America"
country_code2: "US"
country_code3: "USA"
country_name: "United States"
country_name_official: "United States of America"
country_capital: "Washington, D.C."
state_prov: "California"
state_code: "US-CA"
district: "Santa Clara County"
city: "Mountain View"
zipcode: "94043"
latitude: "37.42240"
longitude: "-122.08421"
is_eu: false
country_flag: "https://ipgeolocation.io/static/flags/us_64.png"
geoname_id: "5375480"
country_emoji: "\U0001F1FA\U0001F1F8"
country_metadata:
calling_code: "+1"
tld: ".us"
languages:
- "en-US"
- "es-US"
- "haw"
- "fr"
network:
connection_type: ""
route: "8.8.8.0/24"
is_anycast: true
is_cdn: false
cdn_provider_name: ""
currency:
code: "USD"
name: "US Dollar"
symbol: "$"
asn:
as_number: "AS15169"
organization: "Google LLC"
country: "US"
type: "BUSINESS"
domain: "google.com"
date_allocated: "2000-03-30"
rir: "ARIN"
company:
name: "Google LLC"
type: "HOSTING"
domain: "google.com"
time_zone:
name: "America/Los_Angeles"
offset: -8
offset_with_dst: -8
current_time: "2026-02-09 09:54:51.206-0800"
current_time_unix: 1770659691.206
current_tz_abbreviation: "PST"
current_tz_full_name: "Pacific Standard Time"
standard_tz_abbreviation: "PST"
standard_tz_full_name: "Pacific Standard Time"
is_dst: false
dst_savings: 0
dst_exists: true
dst_tz_abbreviation: "PDT"
dst_tz_full_name: "Pacific Daylight Time"
dst_start:
utc_time: "2026-03-08 TIME 10:00"
duration: "+1.00H"
gap: true
date_time_after: "2026-03-08 TIME 03:00"
date_time_before: "2026-03-08 TIME 02:00"
overlap: false
dst_end:
utc_time: "2026-11-01 TIME 09:00"
duration: "-1.00H"
gap: false
date_time_after: "2026-11-01 TIME 01:00"
date_time_before: "2026-11-01 TIME 02:00"
overlap: true
- message: "'10.0.0.1' is a bogon IP address."
"400":
description: |
Bad request. Returned for one of the following reasons:
- The provided IPv4 address, IPv6 address, or domain name is invalid.
- Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,
either in a parameter name or its value (especially in the API key).
- For the `ipgeo-bulk` endpoint:
- The request payload is empty or missing.
- The JSON body is malformed.
- The `ips` field is missing or the `ips` array is empty.
- More than 50,000 IP addresses are provided in the request.
- An invalid or unsupported `lang` parameter is provided.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
invalidIp:
summary: Invalid IPv4/IPv6/domain input
value:
message: "Provided name, service or IP address '999.999.999.999' is not valid."
specialCharacters:
summary: Special characters in API URL or key
value:
message: "Invalid character found in the request target."
malformedJson:
summary: Malformed JSON body for bulk endpoint
value:
message: "Malformed JSON request or invalid field"
missingIps:
summary: Bulk body missing ips field
value:
message: "IP addresses for bulk lookup are missing"
emptyBulkIps:
summary: Bulk ips array is empty
value:
message: "'ips' must not be empty or null"
tooManyBulkEntries:
summary: Bulk body exceeds 50,000 entries
value:
message: "No. of lookup queries cannot be more than 50000"
invalidLang:
summary: Unsupported lang parameter value
value:
message: "This 'zz' lang is not valid. Please use 'en' as the default language"
"401":
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing.
- An invalid (random or incorrect) API key is provided.
- The account has been disabled or locked due to abuse or illegal activity.
- The API request is made using an API key for a database subscription.
- The subscription is in a 'paused' state.
- The subscription trial has expired.
- The account’s active-until date has passed and renewal or upgrade is required.
- Any of the following `include` values are used with a Free/Developer plan API key:
`hostname`, `liveHostname`, `hostnameFallbackLive`, `security`,
`abuse`, `geo_accuracy`, `dma_code`, or `user_agent`.
- The bulk IP geolocation endpoint is called using a Free subscription API key.
- The bulk IP geolocation endpoint is called using Request Origin (CORS)
authentication. Bulk requests require an `apiKey` and cannot be authenticated
using Request Origin alone.
- A domain name lookup is performed using a Free subscription API key.
- A language other than English is specified in the `lang` parameter
while using a Free/Developer plan API key.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscriptionKey:
summary: Database subscription API key used for REST API
value:
message: "You cannot query IPGeolocation API on a database plan subscription. "
pausedSubscription:
summary: Subscription is paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired or trial ended
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
freePlanBulk:
summary: Free plan used for bulk endpoint
value:
message: "Bulk IP to geolocation lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
requestOriginBulk:
summary: Bulk endpoint called using Request Origin authentication
value:
message: "Bulk queries are not allowed with request origins. Please use an API key to perform bulk queries."
freePlanInclude:
summary: Free plan used with restricted include parameter
value:
message: "This feature is not supported on your subscription. This feature is available on Paid subscriptions only."
freePlanDomain:
summary: Free plan used with domain lookup
value:
message: "IP to geolocation lookup for domain or service name is not supported on your current subscription. This feature is available to all paid subscriptions only."
freePlanLang:
summary: Free plan used with non-English lang value
value:
message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"413":
$ref: "#/components/responses/PayloadTooLarge"
"415":
$ref: "#/components/responses/UnsupportedMediaType"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/getip:
get:
operationId: getCallerIp
summary: Get caller's public IP address
description: |
Returns the public IP address of the client that calls this endpoint. If
called from a server, this returns the server's IP. If called from a browser
via client-side JavaScript, this returns the visitor's public IP address.
This endpoint does not require authentication. It can be called without an
`apiKey` query parameter and without an IPGeolocation.io account.
Use this endpoint when you only need the caller's public IP address. For
full geolocation, network, ASN, and other enrichment data, use
`GET /v3/ipgeo` instead.
tags:
- IP Geolocation
security: []
parameters:
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified.
If `output` is unknown or unsupported, it is ignored and the response
defaults to JSON (`application/json`) with HTTP 200.
schema:
type: string
enum:
- "json"
- "xml"
- "text"
default: "json"
examples:
json:
summary: JSON response (default)
value: "json"
xml:
summary: XML response
value: "xml"
text:
summary: Plain text response
value: "text"
responses:
"200":
description: The caller's public IP address.
content:
application/json:
schema:
$ref: "#/components/schemas/GetIpResponse"
example:
ip: "8.8.8.8"
application/xml:
schema:
$ref: "#/components/schemas/GetIpResponse"
example: |
8.8.8.8
text/plain:
schema:
type: string
description: |
The caller's public IP address as a raw string, with no surrounding
JSON or XML.
example: "8.8.8.8"
example: "8.8.8.8"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/security:
get:
operationId: lookupIpSecurity
security:
- ApiKeyAuth: []
summary: Single IP Security Lookup
description: |
Returns threat intelligence and anonymization signals for a single
IPv4 or IPv6 address.
If the `ip` parameter is omitted, the API automatically detects the
caller's public IP address and returns its security risk signals.
The response includes a threat score and multiple indicators such
as VPN usage, proxy usage, Tor exit node detection, relay networks,
bot activity, spam activity, and cloud hosting infrastructure.
When available, provider names, confidence scores, and last-seen
timestamps are included.
Use the `fields` and `excludes` parameters to control which parts
of the response are returned.
tags:
- IP Security
parameters:
- name: ip
in: query
required: false
description: |
An IPv4 address or IPv6 address to look up. When omitted, the API
resolves the public IP of the requesting client. Empty or whitespace-only values
are treated the same as omission and resolve caller IP. Pass `ip` only once. If multiple `ip` query parameters are sent,
values may be merged and treated as invalid input (HTTP 400).
schema:
type: string
example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
- name: fields
in: query
required: false
description: |
Comma-separated list of fields or objects to return. Everything else is omitted.
The `ip` field is always returned regardless of this filter.
Supports dot-notation for nested fields: `security.is_tor`, `security.threat_score`.
If the same nested field path is specified in both `fields` and `excludes`
(e.g. `fields=security.is_vpn&excludes=security.is_vpn`), that field is returned
as an empty value. Specifying the same top-level object name in both (e.g.
`fields=security&excludes=security`) has no emptying effect — the full object
is returned.
If you list both an object key and one of its nested fields separated by comma
(e.g. `security,security.is_vpn`), the full object is returned.
Unknown field paths are ignored. The API still returns HTTP 200.
This parameter only has an effect once a request is authorized; the IP Security
API as a whole requires a paid plan.
schema:
type: string
example: "security.is_tor,security.is_vpn"
- name: excludes
in: query
required: false
description: |
Comma-separated list of fields or objects to remove from the response. The `ip`
field cannot be excluded.
Supports dot-notation for nested fields: `security.is_relay`.
If the same nested field path is specified in both `fields` and `excludes`
(e.g. `fields=security.is_vpn&excludes=security.is_vpn`), that field is returned
as an empty value. Specifying the same top-level object name in both (e.g.
`fields=security&excludes=security`) has no emptying effect — the full object
is returned.
Unknown fields or object keys in `excludes` are ignored. The API still returns
HTTP 200.
This parameter only has an effect once a request is authorized; the IP Security
API as a whole requires a paid plan.
schema:
type: string
example: "security.proxy_provider_names,security.is_residential_proxy"
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
responses:
"200":
description: Security intelligence for the requested IP.
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: "#/components/schemas/IpSecurityResponse"
example:
ip: "2.56.188.34"
security:
threat_score: 80
is_tor: false
is_proxy: true
proxy_provider_names: [
"Zyte Proxy"
]
proxy_confidence_score: 80
proxy_last_seen: "2025-12-12"
is_residential_proxy: true
is_vpn: true
vpn_provider_names: [
"Nord VPN"
]
vpn_confidence_score: 80
vpn_last_seen: "2026-01-19"
is_relay: false
relay_provider_name: ""
is_anonymous: true
is_known_attacker: true
is_bot: false
bot_confidence_score: 0
bot_operator_name: ""
bot_type: ""
is_known_good_bot: false
bot_last_seen: ""
is_spam: false
is_cloud_provider: true
cloud_provider_name: "Packethub S.A."
is_corporate_gateway: false
corporate_gateway_type: ""
corporate_gateway_provider_name: ""
"400":
description: |
Bad request. Returned for one of the following reasons:
- The provided IPv4 or IPv6 address is invalid. This API does not accept domain
names in the `ip` parameter — a domain name is rejected the same way as any
other non-IP string.
- Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,
either in a parameter name or its value (especially in the API key).
- For the `security-bulk` endpoint:
- The request payload is empty or missing.
- The JSON body is malformed.
- The `ips` field is missing or the `ips` array is empty.
- More than 50,000 IP addresses are provided in the request.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
invalidIp:
summary: Invalid IPv4/IPv6 input
value:
message: "Provided IP address '999.999.999.999' is not valid."
specialCharacters:
summary: Special characters in API URL or key
value:
message: "Invalid character found in the request target."
malformedJson:
summary: Malformed JSON body for bulk endpoint
value:
message: "Malformed JSON request or invalid field"
missingIps:
summary: Bulk body missing ips field
value:
message: "IP addresses for bulk lookup are missing"
emptyBulkIps:
summary: Bulk ips array is empty
value:
message: "'ips' must not be empty or null"
tooManyBulkEntries:
summary: Bulk body exceeds 50,000 entries
value:
message: "No. of lookup queries cannot be more than 50000"
"401":
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing.
- An invalid (random or incorrect) API key is provided.
- The account has been disabled or locked due to abuse or illegal activity.
- The API request is made using an API key for a database subscription.
- The API request is made using a free subscription API key.
- The subscription is in a 'paused' state.
- The subscription trial has expired.
- The account’s active-until date has passed and renewal or upgrade is required.
- The bulk IP security lookup endpoint is called using a free subscription API key.
- The bulk IP security lookup endpoint is called using Request Origin (CORS)
authentication. Bulk requests require an `apiKey` and cannot be authenticated
using Request Origin alone.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscriptionKey:
summary: Database subscription API key used for REST API
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
freePlanAccess:
summary: Free subscription used for single IP Security lookup
value:
message: "IP Security Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
freePlanAccessBulk:
summary: Free subscription used for bulk IP Security lookup
value:
message: "Bulk IP Security Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
pausedSubscription:
summary: Subscription is paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
trialExpired:
summary: Subscription trial has expired
value:
message: "Your subscription trial has been expired. Please subscribe to a paid plan to use IPGeolocation API."
subscriptionExpired:
summary: Subscription active-until date has passed
value:
message: "Your subscription has expired at 2026-01-15 00:00. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
requestOriginBulk:
summary: Bulk endpoint called using Request Origin authentication
value:
message: "Bulk queries are not allowed with request origins. Please use an API key to perform bulk queries."
"404":
description: |
Not found. Returned for one of the following reasons:
- A syntactically valid IPv4 or IPv6 address does not exist in the IPGeolocation database.
- An IPv4 address, IPv6 address, or domain name is passed as a path variable
instead of as a URL query parameter (e.g., using `/v3/ipgeo/8.8.8.8`
instead of `/v3/ipgeo?ip=8.8.8.8`).
- A non-existent or incorrect API endpoint is called.
Invalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
ipNotInDatabase:
summary: IPv4/IPv6 not found in database
value:
message: "Provided IPv4 or IPv6 address does not exist in our database."
ipAsPathVariable:
summary: IP passed as path variable instead of query parameter
value:
message: "No endpoint GET /v3/ipgeo/8.8.8.8."
wrongEndpoint:
summary: Incorrect or non-existent endpoint
value:
message: "No endpoint GET /v3/security-invalid."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/security-bulk:
post:
operationId: bulkLookupIpSecurity
security:
- ApiKeyAuth: []
summary: Bulk IP Security Lookup
description: |
Returns security intelligence for up to **50,000 IPv4 or IPv6
addresses** in a single request.
The request body must contain an `ips` array.
Each IP is processed independently. Invalid, bogon, or private
IP addresses return an object containing only a `message` field.
Credits are charged **per valid IP address** using the same
pricing rules as the single lookup endpoint.
When at least one entry is invalid, the response header
`X-Successful-Record` indicates the number of successful
lookups.
Only the `POST` method is supported for this endpoint.
tags:
- IP Security
parameters:
- name: fields
in: query
required: false
description: |
Comma-separated list of fields or objects to return. Everything else is omitted.
The `ip` field is always returned regardless of this filter.
Supports dot-notation for nested fields: `security.is_tor`, `security.threat_score`.
If the same nested field path is specified in both `fields` and `excludes`
(e.g. `fields=security.is_vpn&excludes=security.is_vpn`), that field is returned
as an empty value. Specifying the same top-level object name in both (e.g.
`fields=security&excludes=security`) has no emptying effect — the full object
is returned.
If you list both an object key and one of its nested fields separated by comma
(e.g. `security,security.is_vpn`), the full object is returned.
Unknown field paths are ignored. The API still returns HTTP 200.
This parameter only has an effect once a request is authorized; the IP Security
API as a whole requires a paid plan.
schema:
type: string
example: "security.is_tor,security.is_vpn"
- name: excludes
in: query
required: false
description: |
Comma-separated list of fields or objects to remove from the response. The `ip`
field cannot be excluded.
Supports dot-notation for nested fields: `security.is_relay`.
If the same nested field path is specified in both `fields` and `excludes`
(e.g. `fields=security.is_vpn&excludes=security.is_vpn`), that field is returned
as an empty value. Specifying the same top-level object name in both (e.g.
`fields=security&excludes=security`) has no emptying effect — the full object
is returned.
Unknown fields or object keys in `excludes` are ignored. The API still returns
HTTP 200.
This parameter only has an effect once a request is authorized; the IP Security
API as a whole requires a paid plan.
schema:
type: string
example: "security.proxy_provider_names,security.is_residential_proxy"
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
requestBody:
required: true
description: |
A JSON object containing an `ips` array. Each element is a string representing
an IPv4 address or IPv6 address. The array must not be empty and
must not contain more than 50,000 entries.
content:
application/json:
schema:
$ref: "#/components/schemas/BulkSecurityRequest"
examples:
mixedIps:
summary: Mixed IPv4 and IPv6
value:
ips:
- "8.8.8.8"
- "91.128.103.196"
- "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
ipv4Only:
summary: Multiple IPv4 addresses
value:
ips:
- "8.8.8.8"
- "8.8.4.4"
- "165.227.0.0"
responses:
"200":
description: |
An array of results, one per input IP address.
Valid entries return a security lookup object containing the IP address
and its associated security intelligence.
Invalid, private, or bogon IP addresses return an object containing only
a `message` field.
The `X-Successful-Record` response header is returned only when the request
contains one or more invalid entries and indicates the number of successful
lookups.
headers:
X-Credits-Charged:
description: |
Total number of API credits consumed. Equals credits per lookup
multiplied by the count of valid IPs.
schema:
type: number
example: 3
X-Successful-Record:
description: |
Number of valid IP addresses that were successfully resolved in
this bulk request. Invalid, bogon, and private IPs are not counted.
This header is included only when at least one bulk entry returns an
error message and total successful lookups are fewer than submitted
entries.
schema:
type: number
example: 4
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/BulkSecurityResponseItem"
example:
- ip: "2.56.188.34"
security:
threat_score: 80
is_tor: false
is_proxy: true
proxy_provider_names: [
"Zyte Proxy"
]
proxy_confidence_score: 80
proxy_last_seen: "2025-12-12"
is_residential_proxy: true
is_vpn: true
vpn_provider_names: [
"Nord VPN"
]
vpn_confidence_score: 80
vpn_last_seen: "2026-01-19"
is_relay: false
relay_provider_name: ""
is_anonymous: true
is_known_attacker: true
is_bot: false
bot_confidence_score: 0
bot_operator_name: ""
bot_type: ""
is_known_good_bot: false
bot_last_seen: ""
is_spam: false
is_cloud_provider: true
cloud_provider_name: "Packethub S.A."
is_corporate_gateway: false
corporate_gateway_type: ""
corporate_gateway_provider_name: ""
- message: "'10.0.0.1' is a bogon IP address."
"400":
description: |
Bad request. Returned for one of the following reasons:
- The provided IPv4 or IPv6 address is invalid. This API does not accept domain
names in the `ip` parameter — a domain name is rejected the same way as any
other non-IP string.
- Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,
either in a parameter name or its value (especially in the API key).
- For the `security-bulk` endpoint:
- The request payload is empty or missing.
- The JSON body is malformed.
- The `ips` field is missing or the `ips` array is empty.
- More than 50,000 IP addresses are provided in the request.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
invalidIp:
summary: Invalid IPv4/IPv6 input
value:
message: "Provided IP address '999.999.999.999' is not valid."
specialCharacters:
summary: Special characters in API URL or key
value:
message: "Invalid character found in the request target."
malformedJson:
summary: Malformed JSON body for bulk endpoint
value:
message: "Malformed JSON request or invalid field"
missingIps:
summary: Bulk body missing ips field
value:
message: "IP addresses for bulk lookup are missing"
emptyBulkIps:
summary: Bulk ips array is empty
value:
message: "'ips' must not be empty or null"
tooManyBulkEntries:
summary: Bulk body exceeds 50,000 entries
value:
message: "No. of lookup queries cannot be more than 50000"
"401":
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing.
- An invalid (random or incorrect) API key is provided.
- The account has been disabled or locked due to abuse or illegal activity.
- The API request is made using an API key for a database subscription.
- The API request is made using a free subscription API key.
- The subscription is in a 'paused' state.
- The subscription trial has expired.
- The account’s active-until date has passed and renewal or upgrade is required.
- The bulk IP security lookup endpoint is called using a free subscription API key.
- The bulk IP security lookup endpoint is called using Request Origin (CORS)
authentication. Bulk requests require an `apiKey` and cannot be authenticated
using Request Origin alone.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscriptionKey:
summary: Database subscription API key used for REST API
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
freePlanAccess:
summary: Free subscription used for single IP Security lookup
value:
message: "IP Security Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
freePlanAccessBulk:
summary: Free subscription used for bulk IP Security lookup
value:
message: "Bulk IP Security Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
pausedSubscription:
summary: Subscription is paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
trialExpired:
summary: Subscription trial has expired
value:
message: "Your subscription trial has been expired. Please subscribe to a paid plan to use IPGeolocation API."
subscriptionExpired:
summary: Subscription active-until date has passed
value:
message: "Your subscription has expired at 2026-01-15 00:00. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
requestOriginBulk:
summary: Bulk endpoint called using Request Origin authentication
value:
message: "Bulk queries are not allowed with request origins. Please use an API key to perform bulk queries."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"413":
$ref: "#/components/responses/PayloadTooLarge"
"415":
$ref: "#/components/responses/UnsupportedMediaType"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/asn:
get:
operationId: lookupASN
security:
- ApiKeyAuth: []
summary: ASN Lookup
description: |
Returns ASN details for a single IPv4 address, IPv6 address,
or ASN number.
The response contains information about the Autonomous System
responsible for routing the queried IP address or ASN.
Basic ASN metadata is always returned, while additional routing
relationships such as peers, upstreams, downstreams, routes,
and WHOIS data can be retrieved using the `include` parameter.
When the lookup is performed using the `asn` parameter,
the `ip` field is not included in the response.
Each successful lookup consumes **1 credit**.
Use the `fields`, `excludes`, and `include` parameters
to customize the response.
tags:
- ASN Lookup
parameters:
- name: ip
in: query
required: false
description: |
An IPv4 address or IPv6 address to look up. When omitted, the API
resolves the public IP of the requesting client.
If the `asn` parameter is provided, the `ip` parameter must not be used,
because the lookup will be performed directly using the specified ASN.
Empty or whitespace-only values are treated the same as omission and resolve
the caller IP.
Pass `ip` only once. If multiple `ip` query parameters are sent,
values may be merged and treated as invalid input (HTTP 400).
schema:
type: string
example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
- name: asn
in: query
required: false
description: |
An Autonomous System Number (ASN) to look up.
When provided, the lookup is performed directly using the specified ASN,
and the `ip` parameter must not be included in the request.
The API returns detailed information about the ASN including the
organization name, country of registration, ASN type, routing statistics,
and other related network metadata.
Pass `asn` only once. If multiple `asn` query parameters are sent,
values may be merged and treated as invalid input (HTTP 400).
Accepted numeric values (after stripping an optional `AS` prefix) range
from 1 to 4294967295 (the full 32-bit ASN range per RFC 6793). A
non-numeric value or a value outside this range returns HTTP 400
(see the `invalidAsnQuery` example on the Bad Request response).
schema:
type: string
example: "AS24940"
- name: include
in: query
required: false
description: |
Comma-separated list of optional data modules to add to the response. These are
not returned by default.
Supported ASN modules include:
- `peers`
- `downstreams`
- `upstreams`
- `routes`
- `whois_response`
If multiple values are provided, they must be comma-separated.
For additional query parameters (`include`, `fields`, `excludes`, `output`),
unknown values are ignored. The API still returns HTTP 200 and applies only
recognized values.
schema:
type: string
example: "peers,downstreams,upstreams,routes,whois_response"
- name: fields
in: query
required: false
description: |
Comma-separated list of fields or objects to return. Everything else is omitted.
The `ip` field is always returned when the lookup is performed using an IP address.
Supports dot-notation for nested fields: `asn.organization`, `asn.domain`.
If the same nested field path is specified in both `fields` and `excludes`
(e.g. `asn.organization` in both), the object is still returned, but it will
be empty. Duplicating a bare top-level object name (e.g. `asn` in both
`fields` and `excludes`) has no emptying effect; the full object is returned.
If you list both an object key and one of its nested fields separated by comma
(e.g. `asn,asn.organization`), the full object is returned.
Unknown field paths are ignored. The API still returns HTTP 200.
The ASN lookup endpoint itself requires a paid plan; this parameter only
applies once a request is authorized.
schema:
type: string
example: "asn.organization,asn.country"
- name: excludes
in: query
required: false
description: |
Comma-separated list of fields or objects to remove from the response.
The `ip` field cannot be excluded.
Supports dot-notation for nested fields: `asn.domain`.
If the same nested field path is specified in both `fields` and `excludes`
(e.g. `asn.organization` in both), the object is still returned, but it will
be empty. Duplicating a bare top-level object name (e.g. `asn` in both
`fields` and `excludes`) has no emptying effect; the full object is returned.
Unknown fields or object keys in `excludes` are ignored. The API still returns
HTTP 200.
The ASN lookup endpoint itself requires a paid plan; this parameter only
applies once a request is authorized.
schema:
type: string
example: "asn.date_allocated,asn.allocation_status"
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
responses:
"200":
description: ASN information for the requested IP address.
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: "#/components/schemas/ASNLookupResponse"
example:
asn:
as_number: "AS24940"
organization: "Hetzner Online GmbH"
country: "DE"
type: "HOSTING"
domain: "hetzner.com"
date_allocated: "2002-06-03"
asn_name: "HETZNER-AS"
allocation_status: "ASSIGNED"
num_of_ipv4_routes: "84"
num_of_ipv6_routes: "6"
rir: "RIPE"
peers:
- as_number: "AS58057"
description: "Securebit A"
country: "CH"
- as_number: "AS28792"
description: "Public Internet Ltd"
country: "GB"
routes:
- "78.46.0.0/15"
- "138.199.128.0/17"
upstreams:
- as_number: "AS12552"
description: "GlobalConnect AB"
country: "SE"
- as_number: "AS58057"
description: "Securebit AG"
country: "CH"
downstreams:
- as_number: "AS209148"
description: "Securepoint GmbH"
country: "DE"
- as_number: "AS198167"
description: "Apptc.me s.r.o."
country: "CZ"
whois_response: |
#
# ARIN WHOIS data and services are subject to the Terms of Use
#
ASNumber: 24940
ASName: HETZNER-AS
OrgName: Hetzner Online GmbH
Country: DE
...
"404":
description: |
Not found. Returned for one of the following reasons:
- A syntactically valid IPv4, IPv6, or ASN does not exist in the IPGeolocation database.
- A syntactically valid IP address resolves successfully but has no ASN
associated with it in the database.
- An IPv4, IPv6, or ASN is passed as a path variable
instead of as a URL query parameter (e.g., using `/v3/asn/8.8.8.8`
instead of `/v3/asn?ip=8.8.8.8`).
- A non-existent or incorrect API endpoint is called.
Invalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
ipNotInDatabase:
summary: IPv4/IPv6/ASN not found in database
value:
message: "Provided ASN or IP Address '24940' doesn't exist in our database."
asnForIpNotFound:
summary: IP resolves but has no associated ASN in the database
value:
message: "Provided IP Address '8.8.8.8' doesn't have an associated ASN in our database."
ipAsPathVariable:
summary: IP passed as path variable instead of query parameter
value:
message: "No endpoint GET /v3/asn/8.8.8.8."
asnAsPathVariable:
summary: ASN passed as path variable instead of query parameter
value:
message: "No endpoint GET /v3/asn/24940."
wrongEndpoint:
summary: Incorrect or non-existent endpoint
value:
message: "No endpoint GET /v3/asn-invalid."
"400":
description: |
Bad request. Returned for one of the following reasons:
- The provided IPv4 address or IPv6 address is invalid.
- The provided `asn` value is non-numeric (once any `AS` prefix is stripped)
or outside the accepted range of 1-4294967295.
- Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,
either in a parameter name or its value (especially in the API key).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
invalidIp:
summary: Invalid IPv4/IPv6 input
value:
message: "Provided IP address '999.999.999.999' is not valid."
invalidAsnQuery:
summary: Non-numeric or out-of-range ASN value
value:
message: "Provided ASN 'abc' is not valid."
specialCharacters:
summary: Special characters in API URL or key
value:
message: "Invalid character found in the request target."
"401":
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing.
- An invalid (random or incorrect) API key is provided.
- The account has been disabled or locked due to abuse or illegal activity.
- The API request is made using an API key for a database subscription.
- The API request is made using a free subscription API key.
- The subscription is in a 'paused' state.
- The subscription trial has expired.
- The account’s active-until date has passed and renewal or upgrade is required.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscriptionKey:
summary: Database subscription API key used for REST API
value:
message: "You cannot query IPGeolocation API on a database plan subscription. "
freePlanAccess:
summary: Free subscription used for ASN lookup API
value:
message: "ASN Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
pausedSubscription:
summary: Subscription is paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired or trial ended
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/abuse:
get:
operationId: lookupIpAbuseContact
security:
- ApiKeyAuth: []
summary: IP Abuse Contact Lookup
description: |
Returns abuse contact information for a single IPv4 or IPv6 address.
The response includes the organization responsible for handling abuse
complaints related to the queried IP address. This typically contains
the abuse contact role, organization name, contact emails, phone
numbers, and the registered address.
This endpoint is intended for reporting malicious activities such as
spam, phishing, DDoS attacks, and other network abuse.
When only abuse contact information is required, using this endpoint is
recommended instead of `/v3/ipgeo?include=abuse` because it returns a
smaller response payload and predictable credit usage.
Each successful lookup consumes **1 credit**.
Use the `fields` and `excludes` parameters to control which parts of
the response are returned.
tags:
- IP Abuse Contact
parameters:
- name: ip
in: query
required: false
description: |
An IPv4 address or IPv6 address to look up. When omitted, the API
resolves the public IP of the requesting client. Empty or whitespace-only values
are treated the same as omission and resolve caller IP. Pass `ip` only once. If multiple `ip` query parameters are sent,
values may be merged and treated as invalid input (HTTP 400).
schema:
type: string
example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
- name: fields
in: query
required: false
description: |
Comma-separated list of fields or objects to return. Everything else is omitted.
The `ip` field is always returned regardless of this filter.
Supports dot-notation for nested fields: `abuse.route`, `abuse.organization`.
If the same **nested** field path is specified in both `fields` and `excludes`
(e.g. `fields=abuse.name&excludes=abuse.name`), the parent object is still
returned, but that field will be empty. Duplicating a **bare top-level**
object name in both parameters (e.g. `fields=abuse&excludes=abuse`) has no
emptying effect: the full, unfiltered object is returned.
If you list both an object key and one of its nested fields separated by comma
(e.g. `abuse,abuse.name`), the full object is returned.
Unknown field paths are ignored. The API still returns HTTP 200.
Available on all plans including Free.
schema:
type: string
example: "abuse.name,abuse.organization"
- name: excludes
in: query
required: false
description: |
Comma-separated list of fields or objects to remove from the response. The `ip`
field cannot be excluded.
Supports dot-notation for nested fields: `abuse.name`.
If the same **nested** field path is specified in both `fields` and `excludes`
(e.g. `fields=abuse.name&excludes=abuse.name`), the parent object is still
returned, but that field will be empty. Duplicating a **bare top-level**
object name in both parameters (e.g. `fields=abuse&excludes=abuse`) has no
emptying effect: the full, unfiltered object is returned.
Unknown fields or object keys in `excludes` are ignored. The API still returns
HTTP 200.
Available on all plans including Free.
schema:
type: string
example: "abuse.address,abuse.emails"
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `Accept` header
takes precedence; `output` is used only as a fallback when the `Accept`
header is absent or set to `*/*`.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
responses:
"200":
description: Abuse contact information for the requested IP address.
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: "#/components/schemas/AbuseLookupResponse"
example:
ip: "1.0.0.0"
abuse:
route: "1.0.0.0/24"
country: "AU"
name: "IRT-APNICRANDNET-AU"
organization: ""
kind: "group"
address: "PO Box 3646, South Brisbane, QLD 4101, Australia"
emails:
- "helpdesk@apnic.net"
phone_numbers:
- "+61738583100"
"404":
description: |
Not found. Returned for one of the following reasons:
- A syntactically valid IPv4 or IPv6 address does not exist in the IPGeolocation database.
- An IPv4 address or IPv6 address is passed as a path variable
instead of as a URL query parameter (e.g., using `/v3/ipgeo/8.8.8.8`
instead of `/v3/ipgeo?ip=8.8.8.8`).
- A non-existent or incorrect API endpoint is called.
Invalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
ipNotInDatabase:
summary: IPv4/IPv6 not found in database
value:
message: "Provided IP Address '203.0.113.5' doesn't exist in our database."
ipAsPathVariable:
summary: IP passed as path variable instead of query parameter
value:
message: "No endpoint GET /v3/ipgeo/8.8.8.8."
wrongEndpoint:
summary: Incorrect or non-existent endpoint
value:
message: "No endpoint GET /v3/abuse-invalid."
"400":
description: |
Bad request. Returned for one of the following reasons:
- The provided IPv4 address or IPv6 address is invalid.
- Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,
either in a parameter name or its value (especially in the API key).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
invalidIp:
summary: Invalid IPv4/IPv6 input
value:
message: "Provided IP address '999.999.999.999' is not valid."
specialCharacters:
summary: Special characters in API URL or key
value:
message: "Invalid character found in the request target."
"401":
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing.
- An invalid (random or incorrect) API key is provided.
- The account has been disabled or locked due to abuse or illegal activity.
- The API request is made using an API key for a database subscription.
- The API request is made using a free subscription API key.
- The subscription is in a 'paused' state.
- The subscription trial has expired.
- The account’s active-until date has passed and renewal or upgrade is required.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscriptionKey:
summary: Database subscription API key used for REST API
value:
message: "You cannot query IPGeolocation API on a database plan subscription. "
freePlanAccess:
summary: Free subscription used for Abuse Contact API
value:
message: "Abuse Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
pausedSubscription:
summary: Subscription is paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired or trial ended
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/timezone:
get:
operationId: lookupTimezone
security:
- ApiKeyAuth: []
summary: Timezone Lookup
description: |
Returns current date, time, and timezone information for a
specific location or identifier.
The timezone can be resolved using one of several inputs,
including an IANA timezone name (`tz`), geographic coordinates
(`lat` and `long`), location address (`location`), IPv4 or IPv6
address (`ip`), airport codes (`iata_code` or `icao_code`), or
a UN/LOCODE (`lo_code`).
Depending on the lookup method used, additional contextual
information may also be returned in the response:
- `location` object for IP address or location queries
- `airport_details` object for IATA or ICAO code queries
- `lo_code_details` object for UN/LOCODE queries
If multiple lookup parameters are provided in the same request,
the API resolves the timezone using the following priority order:
1. `tz`
2. `lat` and `long`
3. `location`
4. `ip`
5. `iata_code`
6. `icao_code`
7. `lo_code`
If none of the lookup parameters are provided, the API resolves
the timezone using the public IP address of the requesting client.
Each successful lookup consumes **1 credit**.
tags:
- Timezone
parameters:
- name: ip
in: query
required: false
description: |
An IPv4 or IPv6 address to look up. Domain names are not supported; passing one
fails validation as an invalid IP address. When omitted, the API resolves the
public IP of the requesting client. Empty or whitespace-only values are treated
the same as omission and resolve caller IP. Pass `ip` only once. If multiple `ip`
query parameters are sent, values may be merged and treated as invalid input
(HTTP 400).
schema:
type: string
example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
- name: lang
in: query
required: false
description: |
Language code for translated location names. Defaults to `en`. Non-English
responses require a paid plan. Free plans always receive English regardless
of this parameter. Unsupported `lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`. Defaults to `en`.
schema:
type: string
default: "en"
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
- name: lo_code
in: query
required: false
description: |
UN/LOCODE used to determine the timezone of a city or location.
The code consists of a two-letter country code followed by
three alphanumeric characters representing the location.
When used, the response includes a `lo_code_details` object
alongside the `time_zone` object.
schema:
type: string
example: "DEBER"
- name: icao_code
in: query
required: false
description: |
Four-letter ICAO airport code used to determine the timezone
of the airport location.
When used, the response includes an `airport_details` object
containing airport metadata alongside the `time_zone` object.
schema:
type: string
example: "KATL"
- name: iata_code
in: query
required: false
description: |
Three-letter IATA airport code used to determine the timezone
of the airport location.
When used, the response includes an `airport_details` object
containing airport metadata alongside the `time_zone` object.
schema:
type: string
example: "LHR"
- name: long
in: query
required: false
description: |
Longitude coordinate of the location used to determine the
timezone. Must be provided together with the `lat` parameter.
Valid longitude values range from **-180 to 180**.
schema:
type: number
format: float
example: -74.0060
- name: lat
in: query
required: false
description: |
Latitude coordinate of the location used to determine the
timezone. Must be provided together with the `long` parameter.
Valid latitude values range from **-90 to 90**.
schema:
type: number
format: float
example: 40.7128
- name: location
in: query
required: false
description: |
Address or location name used to determine the timezone.
Typically a city-level or region-level address such as
`London, UK` or `New York, USA`.
When this parameter is used, the API returns a `location`
object containing geolocation details alongside the
`time_zone` object.
schema:
type: string
example: "Lahore, Pakistan"
- name: tz
in: query
required: false
description: |
IANA timezone identifier to retrieve timezone information.
When provided, the API returns the current date, time, and timezone
metadata for the specified timezone.
If multiple lookup parameters are provided in the same request,
the `tz` parameter takes the highest priority.
Example identifiers include `Europe/London`, `America/New_York`,
and `Asia/Tokyo`.
schema:
type: string
example: "Australia/Lord_Howe"
responses:
"200":
description: "Successful response"
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/TimezoneLookupResponse'
examples:
ipLookup:
summary: Lookup by IP address (`ip` parameter or caller IP)
value:
ip: "49.12.0.0"
location:
continent_code: "EU"
continent_name: "Europe"
country_code2: "DE"
country_code3: "DEU"
country_name: "Germany"
country_name_official: "Federal Republic of Germany"
is_eu: true
state_prov: "Bavaria"
state_code: "DE-BY"
district: "Cham"
city: "Falkenstein"
zipcode: "93167"
latitude: "49.09745"
longitude: "12.48637"
time_zone:
name: "Europe/Berlin"
offset: 1
offset_with_dst: 1
date: "2026-03-07"
date_time: "2026-03-07 10:37:39"
date_time_txt: "Saturday, March 07, 2026 10:37:39"
date_time_wti: "Sat, 07 Mar 2026 10:37:39 +0100"
date_time_ymd: "2026-03-07T10:37:39+0100"
current_time: "2026-03-07 10:37:39.744+0100"
current_time_unix: 1772876259.744
time_24: "10:37:39"
time_12: "10:37:39 AM"
week: 10
month: 3
year: 2026
year_abbr: "26"
current_tz_abbreviation: "CET"
current_tz_full_name: "Central European Standard Time"
standard_tz_abbreviation: "CET"
standard_tz_full_name: "Central European Standard Time"
is_dst: false
dst_savings: 0
dst_exists: true
dst_tz_abbreviation: "CEST"
dst_tz_full_name: "Central European Summer Time"
dst_start:
utc_time: "2026-03-29 TIME 01:00"
duration: "+1.00H"
gap: true
date_time_after: "2026-03-29 TIME 03:00"
date_time_before: "2026-03-29 TIME 02:00"
overlap: false
dst_end:
utc_time: "2026-10-25 TIME 01:00"
duration: "-1.00H"
gap: false
date_time_after: "2026-10-25 TIME 02:00"
date_time_before: "2026-10-25 TIME 03:00"
overlap: true
locationLookup:
summary: Lookup by location address (`location` parameter)
value:
location:
location_string: "London, UK"
country_name: "United Kingdom"
state_prov: "England"
city: "London"
locality: "Westminster"
latitude: "51.50002"
longitude: "-0.12240"
time_zone:
name: "Europe/London"
offset: 0
offset_with_dst: 1
date: "2026-07-07"
date_time: "2026-07-07 10:37:39"
date_time_txt: "Tuesday, July 07, 2026 10:37:39"
date_time_wti: "Tue, 07 Jul 2026 10:37:39 +0100"
date_time_ymd: "2026-07-07T10:37:39+0100"
current_time: "2026-07-07 10:37:39.744+0100"
current_time_unix: 1783845459.744
time_24: "10:37:39"
time_12: "10:37:39 AM"
week: 28
month: 7
year: 2026
year_abbr: "26"
current_tz_abbreviation: "BST"
current_tz_full_name: "British Summer Time"
standard_tz_abbreviation: "GMT"
standard_tz_full_name: "Greenwich Mean Time"
is_dst: true
dst_savings: 1
dst_exists: true
dst_tz_abbreviation: "BST"
dst_tz_full_name: "British Summer Time"
dst_start:
utc_time: "2026-03-29 TIME 01:00"
duration: "+1.00H"
gap: true
date_time_after: "2026-03-29 TIME 02:00"
date_time_before: "2026-03-29 TIME 01:00"
overlap: false
dst_end:
utc_time: "2026-10-25 TIME 01:00"
duration: "-1.00H"
gap: false
date_time_after: "2026-10-25 TIME 01:00"
date_time_before: "2026-10-25 TIME 02:00"
overlap: true
"400":
description: |
Bad Request – Possible reasons include:
- If the provided IPv4 or IPv6 address is invalid.
- If special character(s) ( ) [ ] { } | ^ ` is passed in the API URL either as parameter or its value. Specially in case of API key.
- If the provided IATA code to the request parameter `iata_code` is not in the format as three letter code AAA.
- If the provided ICAO code to the request parameter `icao_code` is not in the format as four letter code AAAA.
- If the provided UN/LOCODE to the request parameter `lo_code` is not in format as first two characters of country code, followed by the three alphanumeric characters of the city/region.
- If the provided values to the request parameters `lat` and `long` are not numbers, or the values fall outside the acceptable latitude and longitude ranges. The valid range for latitude is between -90 and 90, and for longitude, it is between -180 and 180.
- If the provided time zone name to the query parameter `tz` is wrong or not registered in the IANA time zone database.
- An invalid or unsupported `lang` parameter is provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidIp:
summary: Invalid IPv4 or IPv6 address
value:
message: "'999.999.999.999' is not an IP string literal."
specialCharacters:
summary: Invalid characters in request
value:
message: "Invalid character found in the request target."
invalidIata:
summary: Invalid IATA code format
value:
message: "Invalid IATA code: LH. IATA code must be in the format of AAA."
invalidIcao:
summary: Invalid ICAO code format
value:
message: "Invalid ICAO code: ATL. ICAO code must be in the format of AAAA."
invalidLocode:
summary: Invalid UN/LOCODE format
value:
message: "Invalid LOCode: DER. LOCode must start with the first two characters as alphabets followed by three alphanumeric characters."
invalidCoordinates:
summary: Coordinates out of range
value:
message: "'latitude' (40.7128) or 'longitude' (-700.0060) is not valid. 'latitude' must be between -90.0 and +90.0 and 'longitude' must be between -180.0 and +180.0."
invalidTimezone:
summary: Invalid timezone identifier
value:
message: "Check whether your input values are correct; time_zone_name = Europe/InvalidCity"
invalidLang:
summary: Unsupported language parameter
value:
message: "This 'xx' lang is not valid. Please use 'en' as the default language"
"401":
description: |
Unauthorized – Possible reasons include:
- Missing or invalid API key
- If your account has been disabled or locked to use by the admin due to abuse or illegal activity.
- When the request to Timezone API is made using API key for a database subscription
- When the request to Timezone API is made on the 'paused' subscription.
- If you’re making API requests after your subscription trial has been expired.
- If your active until date has passed and you need to upgrade your account.
- A language other than English is specified in the `lang` parameter
while using a Free/Developer plan API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscription:
summary: Database subscription key used
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
pausedSubscription:
summary: Subscription paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
freePlanLang:
summary: Non-English language requested on Free plan
value:
message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
"404":
description: |
Not found. Returned for one of the following reasons:
- If the IPv4, IPv6 address does not exist in our database.
- If the IPv4, IPv6 address passed as a path variable, instead of url parameter as ip=.
- If the location address provided to the `location` parameter is invalid. A city-level or state-level address must be provided.
- If the provided UN/LOCODE, IATA code or ICAO code to the query parameters `lo_code`, `iata_code`, or `icao_code` does not exist in our database.
- If the wrong endpoint is called, that does not exist in our API.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
ipNotInDatabase:
summary: IPv4/IPv6 not found in database
value:
message: "Provided IPv4 or IPv6 address does not exist in our database."
ipAsPathVariable:
summary: IP passed as path variable instead of query parameter
value:
message: "No endpoint GET /v3/timezone/8.8.8.8."
invalidLocation:
summary: Invalid location
value:
message: "We couldn't find the location (Germany, jaakjsdfjhb8wobv). Try a city or state level location address only."
invalidAirportCode:
summary: Invalid IATA or ICAO airport code
value:
message: "'Data not found for the provided airport code: ATL123 Please contact at support@ipgeolocation.io if provided airport code exists.'"
invalidLoCode:
summary: Invalid UN/LOCODE
value:
message: "'Data not found for the provided LO code: USATL1 Please contact at support@ipgeolocation.io if provided LO code exists.'"
wrongEndpoint:
summary: Incorrect or non-existent endpoint
value:
message: "No endpoint GET /v3/timezone-invalid."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/timezone/convert:
get:
operationId: convertTimezone
security:
- ApiKeyAuth: []
summary: Timezone Time Conversion
description: |
Converts a given time between two timezones, locations,
coordinates, airports, or UN/LOCODE identifiers.
The conversion can be performed using one of the following
parameter combinations:
- `tz_from` and `tz_to`
- `location_from` and `location_to`
- `lat_from`, `long_from`, `lat_to`, `long_to`
- `iata_from` and `iata_to`
- `icao_from` and `icao_to`
- `locode_from` and `locode_to`
The optional `time` parameter specifies the time to convert.
Supported formats:
- `yyyy-MM-dd HH:mm`
- `yyyy-MM-dd HH:mm:ss`
If the `time` parameter is omitted, the current time is used
for conversion.
Each successful conversion request consumes **1 credit**.
tags:
- Timezone
parameters:
- name: tz_from
in: query
required: false
description: |
Source timezone identifier (IANA format) used for time conversion.
schema:
type: string
example: "America/New_York"
- name: tz_to
in: query
required: false
description: |
Destination timezone identifier (IANA format) used for time conversion.
schema:
type: string
example: "Asia/Kabul"
- name: time
in: query
required: false
description: |
Date and time to convert.
Supported formats:
- `yyyy-MM-dd HH:mm`
- `yyyy-MM-dd HH:mm:ss`
If omitted, the current time is used.
schema:
type: string
example: "2025-01-30 09:00"
- name: location_from
in: query
required: false
description: |
Source location address used to determine the source timezone.
schema:
type: string
example: "New York, USA"
- name: location_to
in: query
required: false
description: |
Destination location address used to determine the target timezone.
schema:
type: string
example: "Lahore, Pakistan"
- name: lat_from
in: query
required: false
schema:
type: number
format: float
example: 34.0207305
- name: long_from
in: query
required: false
schema:
type: number
format: float
example: -118.6919163
- name: lat_to
in: query
required: false
schema:
type: number
format: float
example: 53.4736827
- name: long_to
in: query
required: false
schema:
type: number
format: float
example: -77.3977062
- name: iata_from
in: query
required: false
schema:
type: string
example: "DXB"
- name: iata_to
in: query
required: false
schema:
type: string
example: "LHR"
- name: icao_from
in: query
required: false
schema:
type: string
example: "YSSY"
- name: icao_to
in: query
required: false
schema:
type: string
example: "ZBAA"
- name: locode_from
in: query
required: false
schema:
type: string
example: "PKISB"
- name: locode_to
in: query
required: false
schema:
type: string
example: "USNYC"
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
responses:
"200":
description: Successful response
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/TimeConversionResponse'
example:
original_time: "2026-03-16 21:42:10"
converted_time: "2026-03-16 22:42:10"
diff_hour: 1
diff_min: 60
"400":
description: |
Bad Request – Possible reasons include:
- If one of the query parameters `tz_from` and `tz_to` is provided and the other is missing, for time conversion.
- If one of the query parameters `location_from` and `location_to` is provided and the other is missing, for time conversion.
- If one of the query parameters `lat_from`, `long_from`, `lat_to`, and `long_to` is provided and other(s) is/are missing, for time conversion.
- If the geographic coordinates provided to one of the parameters `lat_from`, `long_from`, `lat_to`, and `long_to` is/are not numbers, or the values fall outside the acceptable latitude and longitude ranges. The valid range for latitude is between -90 and 90, and for longitude, it is between -180 and 180.
- If the time zone names provided to one of the parameters `tz_from` and `tz_to` is/are wrong or not registered in the IANA time zone database.
- If the address provided to either `location_from` or `location_to` can't be resolved to a location. A city-level or state-level address must be provided.
- If none of the query parameter combination is provided for time conversion. `tz_from` and `tz_to` or `location_from` and `location_to` or `lat_from`, `long_from`, `lat_to`, `long_to` combination must be provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
tzPairMissing:
summary: Missing tz_to parameter
value:
message: "To convert time by time zone names , both the tz_from and tz_to parameter must be provided. For more detail, you can read about it in the documentation at ipgeolocation.io or contact us at support@ipgeolocation.io."
locationPairMissing:
summary: Missing location_to parameter
value:
message: "To convert time by Location , both the location_from and location_to parameter must be provided. For more detail, you can read about it in the documentation at ipgeolocation.io or contact us at support@ipgeolocation.io."
coordinatePairMissing:
summary: Missing coordinate parameters
value:
message: "To convert time by coordinates , both the lat_from and long_from parameter must be provided. For more detail, you can read about it in the documentation at ipgeolocation.io or contact us at support@ipgeolocation.io."
invalidCoordinates:
summary: Coordinates out of range
value:
message: "Provided lat_to (450) or long_to (45) is not valid. Latitude must be between -90.0 and +90.0 and longitude must be between -180.0 and +180.0."
invalidTimezone:
summary: Invalid timezone identifier
value:
message: "Check whether your input values are correct; source_time_zone = Europe/InvalidCity, destined_time_zone = Asia/Kabul, date_time = 2025-01-30 09:00"
invalidLocationFrom:
summary: Source location not found
value:
message: "We couldn't find the (from) location (Germany, jaakjsdfjhb8wobv). Try a city or state level address only."
invalidLocationTo:
summary: Destination location not found
value:
message: "We couldn't find the (to) location (Germany, jaakjsdfjhb8wobv). Try a city or state level address only."
noConversionParams:
summary: Missing conversion parameters
value:
message: "Parameters' combination is not complete. 'tz_from' and 'tz_to' or 'location_from' and 'location_to' or 'lat_from' and 'long_from' and 'lat_to' and 'long_to' or 'locode_from' and 'locode_to' or 'iata_from' and 'iata_to' or 'icao_from' and 'icao_to' combinations must be provided."
"401":
description: |
Unauthorized – Possible reasons include:
- Missing or invalid API key
- If your account has been disabled or locked to use by the admin due to abuse or illegal activity.
- When the request to Timezone API is made using API key for a database subscription
- When the request to Timezone API is made on the 'paused' subscription.
- If you’re making API requests after your subscription trial has been expired.
- If your active until date has passed and you need to upgrade your account.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
pausedSubscription:
summary: Subscription paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
"404":
description: |
Not found. Returned for one of the following reasons:
- If the provided UN/LOCODE, IATA code or ICAO code to one of the query
parameters `locode_from`/`locode_to`, `iata_from`/`iata_to`, or
`icao_from`/`icao_to` does not exist in our database.
- If the wrong endpoint is called, that does not exist in our API.
Note: an unresolvable `location_from`/`location_to` address returns HTTP 400,
not 404 — see the 400 response's `invalidLocationFrom`/`invalidLocationTo`
examples.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
invalidAirportCode:
summary: Invalid IATA or ICAO airport code
value:
message: "'Data not found for the provided airport code: ATL123 Please contact at support@ipgeolocation.io if provided airport code exists.'"
invalidLoCode:
summary: Invalid UN/LOCODE
value:
message: "'Data not found for the provided LO code: USATL1 Please contact at support@ipgeolocation.io if provided LO code exists.'"
wrongEndpoint:
summary: Incorrect or non-existent endpoint
value:
message: "No endpoint GET /v3/timezone/convert-invalid."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/user-agent:
get:
operationId: parseUserAgent
security:
- ApiKeyAuth: []
summary: Parse User Agent String (auto-detect or explicit header)
description: |
Parses a user agent string and returns browser, device, and operating system
details. Also detects bots, crawlers, and malicious or malformed user agent strings.
This endpoint supports two usage modes:
**Mode 1 — Auto-detect caller's user agent:**
Omit the `User-Agent` header entirely. The API will parse the user agent string
of the calling client automatically. This is the default browser behavior — when
executed in browser JavaScript, the header is appended automatically and no
additional configuration is needed.
**Mode 2 — Explicit user agent header:**
Pass any user agent string in the `User-Agent` request header. The API parses
that string instead of detecting the caller's own user agent. Use this to
simulate or test specific user agent strings server-side.
Each successful lookup consumes **1 credit**.
tags:
- User Agent
parameters:
- name: User-Agent
in: header
required: false
description: |
The user agent string to parse. When omitted, the API automatically parses
the user agent of the calling client. When provided, the supplied string is
parsed instead.
schema:
type: string
example: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.96 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
responses:
"200":
description: Parsed user agent details for the resolved user agent string.
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: "#/components/schemas/UserAgentResponse"
example:
user_agent_string: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"
name: "Safari"
type: "Browser"
version: "9.0.2"
version_major: "9"
device:
name: "Apple Macintosh"
type: "Desktop"
brand: "Apple"
cpu: "Intel"
engine:
name: "AppleWebKit"
type: "Browser"
version: "601.3.9"
version_major: "601"
operating_system:
name: "Mac OS"
type: "Desktop"
version: "10.11.2"
version_major: "10.11"
build: "??"
"400":
description: |
Bad Request. Returned for one of the following reasons:
- Special characters ( ) [ ] { } | ^ ` are passed in the API URL (either in parameters or values), especially in the API key.
- The `uaString` is empty or null when calling `/v3/user-agent`(POST).
- The `uaStrings` array is empty, or the JSON body does not contain a `uaStrings`
field when calling `/v3/user-agent-bulk`.
- More than 50,000 user agent strings are provided in a single bulk request.
- No `User-Agent` header is present when calling `GET /v3/user-agent`. Unlike the
POST body, there is no alternative way to supply the string for this call, so a
missing/blank header always fails validation.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
specialCharacters:
summary: Invalid special characters in request
value:
message: "Invalid character found in the request target."
emptyUaString:
summary: Empty or null user agent string
value:
message: "User-Agent string must not be blank"
missingUaStringHeader:
summary: Missing User-Agent header on GET
value:
message: "'userAgentString' must not be empty or null"
emptyBulkList:
summary: Empty uaStrings array or missing field
value:
message: "User-Agent strings for bulk lookup are missing"
bulkLimitExceeded:
summary: More than 50,000 strings in bulk request
value:
message: "No. of lookup queries cannot be more than 50000"
"401":
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing from the request.
- The provided API key is not valid.
- The request is made using an API key of a database subscription.
- The account has been disabled or locked due to illegal activity.
- Requests are made after the subscription trial has expired.
- The subscription is paused or not active.
- The account’s active-until date has passed.
- A paid feature is accessed using a free subscription.
- The bulk user agent parsing endpoint is called using a free subscription API key.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscriptionKey:
summary: Database subscription API key used
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
expiredTrial:
summary: Subscription trial expired
value:
message: "Your subscription has expired. Please subscribe to a paid plan to continue using IPGeolocation API."
inactiveSubscription:
summary: Subscription inactive or paused
value:
message: "Your subscription is not active."
expiredAccount:
summary: Account active-until date passed
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
freePlanPaidFeature:
summary: Paid feature accessed on free plan
value:
message: "Custom User-Agent lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
bulkOnFreePlan:
summary: Bulk endpoint called with free subscription key
value:
message: "Bulk User-Agent lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
"404":
description: |
Not Found. Returned when an invalid or non-existent endpoint is called.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "No endpoint GET /v3/user-agent-invalid."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
post:
operationId: parseCustomUserAgent
security:
- ApiKeyAuth: []
summary: Parse Custom User Agent String (payload)
description: |
Parses a custom user agent string supplied in the JSON request body and returns
browser, device, and operating system details.
**Mode 3 — Custom user agent string via POST body:**
Pass the user agent string as the `uaString` field in a JSON payload. This is
intended for server-side use cases where the string to be parsed is different
from the caller's own user agent and is known at request time.
This endpoint is available on **paid plans only**.
Each successful lookup consumes **1 credit**.
tags:
- User Agent
parameters:
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
requestBody:
required: true
description: JSON body containing the custom user agent string to parse.
content:
application/json:
schema:
type: object
required:
- uaString
properties:
uaString:
type: string
description: The custom user agent string to parse.
example: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"
responses:
"200":
description: Parsed user agent details for the submitted user agent string.
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: "#/components/schemas/UserAgentResponse"
example:
user_agent_string: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"
name: "Safari"
type: "Browser"
version: "9.0.2"
version_major: "9"
device:
name: "Apple Macintosh"
type: "Desktop"
brand: "Apple"
cpu: "Intel"
engine:
name: "AppleWebKit"
type: "Browser"
version: "601.3.9"
version_major: "601"
operating_system:
name: "Mac OS"
type: "Desktop"
version: "10.11.2"
version_major: "10.11"
build: "??"
"400":
description: |
Bad Request. Returned for one of the following reasons:
- Special characters ( ) [ ] { } | ^ ` are passed in the API URL (either in parameters or values), especially in the API key.
- The `uaString` is empty or null when calling `/v3/user-agent`(POST).
- The `uaStrings` array is empty, or the JSON body does not contain a `uaStrings`
field when calling `/v3/user-agent-bulk`.
- More than 50,000 user agent strings are provided in a single bulk request.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
specialCharacters:
summary: Invalid special characters in request
value:
message: "Invalid character found in the request target."
emptyUaString:
summary: Empty or null user agent string
value:
message: "User-Agent string must not be blank"
emptyBulkList:
summary: Empty uaStrings array or missing field
value:
message: "User-Agent strings for bulk lookup are missing"
bulkLimitExceeded:
summary: More than 50,000 strings in bulk request
value:
message: "No. of lookup queries cannot be more than 50000"
"401":
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing from the request.
- The provided API key is not valid.
- The request is made using an API key of a database subscription.
- The account has been disabled or locked due to illegal activity.
- Requests are made after the subscription trial has expired.
- The subscription is paused or not active.
- The account’s active-until date has passed.
- A paid feature is accessed using a free subscription.
- The bulk user agent parsing endpoint is called using a free subscription API key.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscriptionKey:
summary: Database subscription API key used
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
expiredTrial:
summary: Subscription trial expired
value:
message: "Your subscription has expired. Please subscribe to a paid plan to continue using IPGeolocation API."
inactiveSubscription:
summary: Subscription inactive or paused
value:
message: "Your subscription is not active."
expiredAccount:
summary: Account active-until date passed
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
freePlanPaidFeature:
summary: Paid feature accessed on free plan
value:
message: "Custom User-Agent lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
bulkOnFreePlan:
summary: Bulk endpoint called with free subscription key
value:
message: "Bulk User-Agent lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
"404":
description: |
Not Found. Returned when an invalid or non-existent endpoint is called.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "No endpoint GET /v3/user-agent-invalid."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"413":
$ref: "#/components/responses/PayloadTooLarge"
"415":
$ref: "#/components/responses/UnsupportedMediaType"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/user-agent-bulk:
post:
operationId: parseUserAgentBulk
security:
- ApiKeyAuth: []
summary: Bulk Parse User Agent Strings
description: |
Parses up to **50,000 user agent strings** in a single request.
Pass a JSON body containing the `uaStrings` array. Each entry in the array
is parsed independently. The total credits charged equals the number of strings
in the array.
This endpoint is available on **paid plans only**.
tags:
- User Agent
parameters:
- name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200. Supported values: `json`, `xml`. Defaults to `json`.
schema:
type: string
default: json
requestBody:
required: true
description: JSON body containing the array of user agent strings to parse.
content:
application/json:
schema:
type: object
required:
- uaStrings
properties:
uaStrings:
type: array
description: |
Array of user agent strings to parse. Maximum 50,000 entries per request.
maxItems: 50000
minItems: 1
items:
type: string
example:
- "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36"
- "Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+"
- "Mozilla/5.0 (Linux; U; en-US) AppleWebKit/528.5+ (KHTML, like Gecko, Safari/528.5+) Version/4.0 Kindle/3.0 (screen 600x800; rotate)"
responses:
"200":
description: |
Array of parsed user agent results, one object per submitted string,
in the same order as the input array.
headers:
X-Credits-Charged:
description: |
Total number of API credits consumed by this request.
Equals the number of user agent strings submitted.
schema:
type: number
example: 3
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/UserAgentResponse"
example:
- user_agent_string: "Mozilla/5.0 (Linux; Android 8.0.0; SM-G960F Build/R16NW) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36"
name: "Chrome"
type: "Browser"
version: "62.0.3202.84"
version_major: "62"
device:
name: "Samsung SM-G960F"
type: "Phone"
brand: "Samsung"
cpu: "Unknown"
engine:
name: "Blink"
type: "Browser"
version: "62.0"
version_major: "62"
operating_system:
name: "Android"
type: "Mobile"
version: "8.0.0"
version_major: "8"
build: "R16NW"
- user_agent_string: "Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+"
name: "Kindle"
type: "Browser"
version: "3.0"
version_major: "3"
device:
name: "Amazon Kindle"
type: "eReader"
brand: "Amazon"
cpu: "ARMv7l"
engine:
name: "AppleWebKit"
type: "Browser"
version: "531.2"
version_major: "531"
operating_system:
name: "FireOS"
type: "Mobile"
version: "??"
version_major: "??"
build: "??"
- user_agent_string: "Mozilla/5.0 (Linux; U; en-US) AppleWebKit/528.5+ (KHTML, like Gecko, Safari/528.5+) Version/4.0 Kindle/3.0 (screen 600x800; rotate)"
name: "Kindle"
type: "Browser"
version: "4.0"
version_major: "4"
device:
name: "Amazon Kindle"
type: "eReader"
brand: "Amazon"
cpu: "Unknown"
engine:
name: "AppleWebKit"
type: "Browser"
version: "528.5"
version_major: "528"
operating_system:
name: "FireOS"
type: "Mobile"
version: "??"
version_major: "??"
build: "??"
"400":
description: |
Bad Request. Returned for one of the following reasons:
- Special characters ( ) [ ] { } | ^ ` are passed in the API URL (either in parameters or values), especially in the API key.
- The `uaString` is empty or null when calling `/v3/user-agent`(POST).
- The `uaStrings` array is empty, or the JSON body does not contain a `uaStrings`
field when calling `/v3/user-agent-bulk`.
- More than 50,000 user agent strings are provided in a single bulk request.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
specialCharacters:
summary: Invalid special characters in request
value:
message: "Invalid character found in the request target."
emptyUaString:
summary: Empty or null user agent string
value:
message: "User-Agent string must not be blank"
emptyBulkList:
summary: Empty uaStrings array or missing field
value:
message: "User-Agent strings for bulk lookup are missing"
bulkLimitExceeded:
summary: More than 50,000 strings in bulk request
value:
message: "No. of lookup queries cannot be more than 50000"
"401":
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing from the request.
- The provided API key is not valid.
- The request is made using an API key of a database subscription.
- The account has been disabled or locked due to illegal activity.
- Requests are made after the subscription trial has expired.
- The subscription is paused or not active.
- The account’s active-until date has passed.
- A paid feature is accessed using a free subscription.
- The bulk user agent parsing endpoint is called using a free subscription API key.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscriptionKey:
summary: Database subscription API key used
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
expiredTrial:
summary: Subscription trial expired
value:
message: "Your subscription has expired. Please subscribe to a paid plan to continue using IPGeolocation API."
inactiveSubscription:
summary: Subscription inactive or paused
value:
message: "Your subscription is not active."
expiredAccount:
summary: Account active-until date passed
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
freePlanPaidFeature:
summary: Paid feature accessed on free plan
value:
message: "Custom User-Agent lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
bulkOnFreePlan:
summary: Bulk endpoint called with free subscription key
value:
message: "Bulk User-Agent lookup is not supported on your current subscription. This feature is available to all paid subscriptions only."
"404":
description: |
Not Found. Returned when an invalid or non-existent endpoint is called.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "No endpoint GET /v3/user-agent-bulk-invalid."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"413":
$ref: "#/components/responses/PayloadTooLarge"
"415":
$ref: "#/components/responses/UnsupportedMediaType"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/astronomy:
get:
operationId: lookupAstronomy
security:
- ApiKeyAuth: []
summary: Astronomy Lookup
description: |
Returns astronomical information for a specific location and date,
including:
- Sunrise and sunset times
- Moonrise and moonset times
- Morning and evening twilight phases (astronomical, nautical, civil)
- Golden hour and blue hour windows (morning and evening)
- Solar noon, day length, and astronomical midnight
- Sun position: altitude, azimuth, distance from Earth
- Moon position: altitude, azimuth, distance from Earth, parallactic angle
- Moon phase, illumination percentage, and angular diameter
The location can be resolved using geographic coordinates (`lat` and
`long`), a location address (`location`), or an IP address (`ip`).
If multiple lookup parameters are provided, the API resolves the
location using the following priority order:
1. `lat` and `long`
2. `location`
3. `ip`
If none of the lookup parameters are provided, the API resolves the
location using the public IP address of the requesting client.
By default, results are calculated for the current date. Pass the
`date` parameter to retrieve data for a specific date.
Each successful lookup consumes **1 credit**.
tags:
- Astronomy
parameters:
- name: lat
in: query
required: false
description: |
Latitude coordinate of the location. Must be provided together with
the `long` parameter.
Valid latitude values range from **-90 to 90**.
schema:
type: number
format: float
example: -27.4748
- name: long
in: query
required: false
description: |
Longitude coordinate of the location. Must be provided together with
the `lat` parameter.
Valid longitude values range from **-180 to 180**.
schema:
type: number
format: float
example: 153.017
- name: location
in: query
required: false
description: |
Address or location name used to determine the astronomical
information. Typically a city-level or region-level address such as
`New York, USA` or `London, UK`.
When this parameter is used, the API returns a `location` object
containing geolocation details alongside the `astronomy` object.
schema:
type: string
example: "London, UK"
- name: ip
in: query
required: false
description: |
An IPv4 or IPv6 address used to resolve the location for the
astronomical lookup. When omitted, the API resolves the public IP
of the requesting client.
When the lookup is performed using an IP address, the response
includes additional geolocation fields in the `location` object
such as continent, country codes, district, and zipcode.
schema:
type: string
example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
- name: date
in: query
required: false
description: |
Date for which to retrieve astronomical information.
Must be in `yyyy-MM-dd` format. Defaults to the current date if
not provided. All astronomical information is calculated at the
current time of day at the resolved location.
schema:
type: string
format: date
example: "2026-03-18"
- name: elevation
in: query
required: false
description: |
Elevation of the location above sea level in meters. Used to
refine astronomical calculations.
When not provided, the elevation of the nearest known city to the
resolved coordinates is used automatically; it falls back to `0`
only when no elevation data is available for that location.
Maximum allowed value is **10,000 meters**; only this upper bound
is enforced (HTTP 400 if exceeded) — negative values are not
clamped and are passed through as provided.
schema:
type: number
format: double
default: 0
minimum: 0
maximum: 10000
example: 1500
- name: time_zone
in: query
required: false
description: |
IANA timezone identifier used to convert all astronomical event
timestamps into the specified timezone.
When provided, all event times (sunrise, sunset, moonrise, moonset,
twilight phases, solar noon, etc.) are returned as full date-time
values (`yyyy-MM-dd HH:mm`) instead of time-only values (`HH:mm`),
and a `time_zone` field is included in the `astronomy` object.
The geographic location used for astronomical calculations remains
unchanged. Only the timestamp representation is converted.
Example: `Europe/London`, `America/New_York`, `Asia/Karachi`.
schema:
type: string
example: "America/New_York"
- name: lang
in: query
required: false
description: |
Language code for translated location names in the `location` object.
Only applies when the lookup is performed via an IP address.
Defaults to `en`. Non-English responses require a paid plan.
Requesting a non-English `lang` value on a Free/Developer plan
returns HTTP 401 (see the `freePlanLang` example under the 401
response) rather than silently falling back to English. Unsupported
`lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`. Defaults to `en`.
schema:
type: string
default: "en"
responses:
"200":
description: Successful response
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/AstronomyLookupResponse'
example:
location:
latitude: "40.76473"
longitude: "-74.00084"
country_name: "United States"
state_prov: "New York"
city: "New York"
locality: "Midtown West"
elevation: "9"
astronomy:
date: "2026-03-18"
current_time: "10:15:00.000"
mid_night: "00:06"
night_end: "04:49"
morning:
astronomical_twilight_begin: "04:49"
astronomical_twilight_end: "05:21"
nautical_twilight_begin: "05:21"
nautical_twilight_end: "05:53"
civil_twilight_begin: "05:53"
civil_twilight_end: "06:20"
blue_hour_begin: "05:42"
blue_hour_end: "06:03"
golden_hour_begin: "06:03"
golden_hour_end: "06:57"
sunrise: "06:20"
sunset: "19:00"
evening:
golden_hour_begin: "18:23"
golden_hour_end: "19:16"
blue_hour_begin: "19:16"
blue_hour_end: "19:38"
civil_twilight_begin: "19:00"
civil_twilight_end: "19:27"
nautical_twilight_begin: "19:27"
nautical_twilight_end: "19:59"
astronomical_twilight_begin: "19:59"
astronomical_twilight_end: "20:31"
night_begin: "20:31"
sun_status: "-"
solar_noon: "12:40"
day_length: "12:40"
sun_altitude: 42.5
sun_distance: 148900000.0
sun_azimuth: 150.3
moon_phase: "WAXING_CRESCENT"
moonrise: "08:45"
moonset: "22:10"
moon_status: "-"
moon_altitude: 15.2
moon_distance: 384400.0
moon_azimuth: 220.5
moon_parallactic_angle: 30.1
moon_illumination_percentage: "25.40"
moon_angle: 357.01
"400":
description: |
Bad Request – Possible reasons include:
- If the provided IPv4 or IPv6 address is invalid.
- If special character(s) `( ) [ ] { } | ^ \`` is passed in the
API URL either as a parameter or its value, especially in the
case of an API key.
- If the provided `date` is not in the format `yyyy-MM-dd`.
- If an invalid or unsupported `lang` parameter is provided.
- If only one of `lat` or `long` is provided; both must be
provided together.
- If the provided values for `lat` and `long` are not numbers,
or fall outside the acceptable ranges. Valid latitude range is
**-90 to 90**; valid longitude range is **-180 to 180**.
- If the provided `elevation` value exceeds the maximum allowed
value of **10,000 meters**.
- If the provided `time_zone` is invalid or unrecognized.
- If the provided IPv4 or IPv6 address does not exist in our
database.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidIp:
summary: Invalid IPv4 or IPv6 address
value:
message: "'999.999.999.999' is not an IP string literal."
specialCharacters:
summary: Invalid characters in request
value:
message: "Invalid character found in the request target."
invalidDate:
summary: Invalid date format
value:
message: "You must provide date in the 'yyyy-MM-dd' format"
missingLat:
summary: Only 'long' provided, 'lat' missing
value:
message: "'lat' must not be null"
missingLong:
summary: Only 'lat' provided, 'long' missing
value:
message: "'long' must not be null"
invalidLatitude:
summary: Latitude out of range
value:
message: "Latitude must be between -90 and 90."
invalidLongitude:
summary: Longitude out of range
value:
message: "Longitude must be between -180 and 180."
invalidElevation:
summary: Elevation exceeds maximum
value:
message: "Elevation cannot be greater than 10000 meters."
invalidTimezone:
summary: Invalid timezone identifier
value:
message: "Check whether your input values are correct; time_zone_name = Europe/InvalidCity"
invalidLang:
summary: Unsupported language parameter
value:
message: "This 'xx' lang is not valid. Please use 'en' as the default language"
ipNotInDatabase:
summary: IP not found in database
value:
message: "Couldn't find astronomy detail for the IP address (8.8.8.8)"
"401":
description: |
Unauthorized – Possible reasons include:
- Missing or invalid API key.
- If your account has been disabled or locked by the admin due
to abuse or illegal activity.
- When the request is made using an API key for a database
subscription.
- When the request is made on a paused subscription.
- If you are making API requests after your subscription trial
has expired.
- If your active-until date has passed and you need to renew
or upgrade your subscription.
- A language other than English is specified in the `lang`
parameter while using a Free/Developer plan API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscription:
summary: Database subscription key used
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
pausedSubscription:
summary: Subscription paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
freePlanLang:
summary: Non-English language on Free plan
value:
message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
"404":
description: |
Not Found. Returned for one of the following reasons:
- If the IPv4 or IPv6 address is passed as a path variable instead
of a URL parameter (`ip=`).
- If the location address provided to the `location` parameter is
invalid. A city-level or state-level address must be provided.
(This applies to this single-date endpoint only; the
`/v3/astronomy/timeSeries` endpoint returns HTTP 400 for this
case instead.)
- If the wrong endpoint is called that does not exist in the API.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
invalidLocation:
summary: Invalid location address
value:
message: "We couldn't find the location 'InvalidCity, XX'. Try a city or state level address only."
wrongEndpoint:
summary: Incorrect or non-existent endpoint
value:
message: "No endpoint GET /v3/astronomy-invalid."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
/v3/astronomy/timeSeries:
get:
operationId: lookupAstronomyTimeSeries
security:
- ApiKeyAuth: []
summary: Astronomy Time Series Lookup
description: |
Returns daily astronomical information for a specific location across
a date range.
The response contains an array of daily astronomy records, each
including sunrise, sunset, moonrise, moonset, twilight phases,
solar noon, day length, and moon phase. Real-time positional data
(altitude, azimuth, distance) is not included in time series
responses.
The location can be resolved using geographic coordinates (`lat` and
`long`), a location address (`location`), or an IP address (`ip`).
**Date range constraints:**
- Both `dateStart` and `dateEnd` are required.
- The maximum allowed span between `dateStart` and `dateEnd` is
**90 days**.
- Both past and future dates are supported within the 90-day window.
Each successful lookup consumes **1 credit** per request.
tags:
- Astronomy
parameters:
- name: lat
in: query
required: false
description: |
Latitude coordinate of the location. Must be provided together with
the `long` parameter.
Valid latitude values range from **-90 to 90**.
schema:
type: number
format: float
example: -27.4748
- name: long
in: query
required: false
description: |
Longitude coordinate of the location. Must be provided together with
the `lat` parameter.
Valid longitude values range from **-180 to 180**.
schema:
type: number
format: float
example: 153.017
- name: location
in: query
required: false
description: |
Address or location name used to determine the astronomical
information. Typically a city-level or region-level address such as
`New York, USA` or `London, UK`.
When this parameter is used, the API returns a `location` object
containing geolocation details alongside the `astronomy` object.
schema:
type: string
example: "London, UK"
- name: ip
in: query
required: false
description: |
An IPv4 or IPv6 address used to resolve the location for the
astronomical lookup. When omitted, the API resolves the public IP
of the requesting client.
When the lookup is performed using an IP address, the response
includes additional geolocation fields in the `location` object
such as continent, country codes, district, and zipcode.
schema:
type: string
example: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
- name: dateStart
in: query
required: true
description: |
Start date of the time series range.
Must be in `yyyy-MM-dd` format. The maximum allowed span between
`dateStart` and `dateEnd` is **90 days**.
schema:
type: string
format: date
example: "2026-03-18"
- name: dateEnd
in: query
required: true
description: |
End date of the time series range.
Must be in `yyyy-MM-dd` format. The maximum allowed span between
`dateStart` and `dateEnd` is **90 days**.
schema:
type: string
format: date
example: "2026-04-18"
- name: elevation
in: query
required: false
description: |
Elevation of the location above sea level in meters. Used to
refine astronomical calculations.
When not provided, the elevation of the nearest known city to the
resolved coordinates is used automatically; it falls back to `0`
only when no elevation data is available for that location.
Maximum allowed value is **10,000 meters**; only this upper bound
is enforced (HTTP 400 if exceeded) — negative values are not
clamped and are passed through as provided.
schema:
type: number
format: double
default: 0
minimum: 0
maximum: 10000
example: 1500
- name: time_zone
in: query
required: false
description: |
IANA timezone identifier used to convert all astronomical event
timestamps into the specified timezone.
When provided, all event times (sunrise, sunset, moonrise, moonset,
twilight phases, solar noon, etc.) are returned as full date-time
values (`yyyy-MM-dd HH:mm`) instead of time-only values (`HH:mm`),
and a `time_zone` field is included in the `astronomy` object.
The geographic location used for astronomical calculations remains
unchanged. Only the timestamp representation is converted.
Example: `Europe/London`, `America/New_York`, `Asia/Karachi`.
schema:
type: string
example: "America/New_York"
- name: lang
in: query
required: false
description: |
Language code for translated location names in the `location` object.
Only applies when the lookup is performed via an IP address.
Defaults to `en`. Non-English responses require a paid plan.
Requesting a non-English `lang` value on a Free/Developer plan
returns HTTP 401 (see the `freePlanLang` example under the 401
response) rather than silently falling back to English. Unsupported
`lang` values return HTTP 400. Language code. Supported values: `en`, `de`, `ru`, `ja`, `fr`, `cn`, `es`, `cs`, `it`, `ko`, `fa`, `pt`, `ar`. Defaults to `en`.
schema:
type: string
default: "en"
responses:
"200":
description: Successful response
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: '#/components/schemas/AstronomyTimeSeriesResponse'
example:
location:
latitude: "40.76473"
longitude: "-74.00084"
country_name: "United States"
state_prov: "New York"
city: "New York"
locality: "Midtown West"
elevation: "9"
astronomy:
- date: "2026-03-18"
mid_night: "00:06"
night_end: "04:49"
morning:
astronomical_twilight_begin: "04:49"
astronomical_twilight_end: "05:21"
nautical_twilight_begin: "05:21"
nautical_twilight_end: "05:53"
civil_twilight_begin: "05:53"
civil_twilight_end: "06:20"
blue_hour_begin: "05:42"
blue_hour_end: "06:03"
golden_hour_begin: "06:03"
golden_hour_end: "06:57"
sunrise: "06:20"
sunset: "19:00"
evening:
golden_hour_begin: "18:23"
golden_hour_end: "19:16"
blue_hour_begin: "19:16"
blue_hour_end: "19:38"
civil_twilight_begin: "19:00"
civil_twilight_end: "19:27"
nautical_twilight_begin: "19:27"
nautical_twilight_end: "19:59"
astronomical_twilight_begin: "19:59"
astronomical_twilight_end: "20:31"
night_begin: "20:31"
sun_status: "-"
solar_noon: "12:40"
day_length: "12:40"
moon_phase: "WAXING_CRESCENT"
moonrise: "08:45"
moonset: "22:10"
moon_status: "-"
- date: "2026-03-19"
mid_night: "00:06"
night_end: "04:47"
morning:
astronomical_twilight_begin: "04:47"
astronomical_twilight_end: "05:19"
nautical_twilight_begin: "05:19"
nautical_twilight_end: "05:51"
civil_twilight_begin: "05:51"
civil_twilight_end: "06:18"
blue_hour_begin: "05:40"
blue_hour_end: "06:01"
golden_hour_begin: "06:01"
golden_hour_end: "06:55"
sunrise: "06:18"
sunset: "19:02"
evening:
golden_hour_begin: "18:25"
golden_hour_end: "19:18"
blue_hour_begin: "19:18"
blue_hour_end: "19:40"
civil_twilight_begin: "19:02"
civil_twilight_end: "19:29"
nautical_twilight_begin: "19:29"
nautical_twilight_end: "20:01"
astronomical_twilight_begin: "20:01"
astronomical_twilight_end: "20:33"
night_begin: "20:33"
sun_status: "-"
solar_noon: "12:40"
day_length: "12:44"
moon_phase: "WAXING_CRESCENT"
moonrise: "09:30"
moonset: "23:05"
moon_status: "-"
"400":
description: |
Bad Request – Possible reasons include:
- If the provided IPv4 or IPv6 address is invalid.
- If special character(s) `( ) [ ] { } | ^ \`` is passed in the
API URL either as a parameter or its value.
- If `dateStart` or `dateEnd` is not in the format `yyyy-MM-dd`.
- If the span between `dateStart` and `dateEnd` is greater than
**90 days**.
- If only one of `lat` or `long` is provided; both must be
provided together.
- If the provided values for `lat` and `long` are not numbers,
or fall outside the acceptable ranges.
- If the provided `elevation` value exceeds **10,000 meters**.
- If the provided `time_zone` is invalid or unrecognized.
- If an invalid or unsupported `lang` parameter is provided.
- If the location address provided to the `location` parameter
is invalid. A city-level or state-level address must be
provided.
- If the provided IPv4 or IPv6 address does not exist in our
database.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidIp:
summary: Invalid IPv4 or IPv6 address
value:
message: "'999.999.999.999' is not an IP string literal."
specialCharacters:
summary: Invalid characters in request
value:
message: "Invalid character found in the request target."
invalidDateFormat:
summary: Invalid date format
value:
message: "You must provide date in the 'yyyy-MM-dd' format"
dateRangeExceeded:
summary: Date range exceeds 90 days
value:
message: "Date range cannot exceed 90 days."
missingLat:
summary: Only 'long' provided, 'lat' missing
value:
message: "'lat' must not be null"
missingLong:
summary: Only 'lat' provided, 'long' missing
value:
message: "'long' must not be null"
invalidLatitude:
summary: Latitude out of range
value:
message: "Latitude must be between -90 and 90."
invalidLongitude:
summary: Longitude out of range
value:
message: "Longitude must be between -180 and 180."
invalidElevation:
summary: Elevation exceeds maximum
value:
message: "Elevation cannot be greater than 10000 meters."
invalidTimezone:
summary: Invalid timezone identifier
value:
message: "Check whether your input values are correct; time_zone_name = Europe/InvalidCity"
invalidLang:
summary: Unsupported language parameter
value:
message: "This 'xx' lang is not valid. Please use 'en' as the default language"
invalidLocation:
summary: Invalid location address
value:
message: "We couldn't find the location 'InvalidCity, XX'. Try a city or state level address only."
ipNotInDatabase:
summary: IP not found in database
value:
message: "Couldn't find astronomy detail for the IP address (8.8.8.8)"
"401":
description: |
Unauthorized – Possible reasons include:
- Missing or invalid API key.
- If your account has been disabled or locked by the admin.
- When the request is made using an API key for a database
subscription.
- When the request is made on a paused subscription.
- If your subscription trial has expired.
- If your active-until date has passed.
- A language other than English is specified in the `lang`
parameter while using a Free/Developer plan API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io"
lockedAccount:
summary: Account locked
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io"
databaseSubscription:
summary: Database subscription key used
value:
message: "You cannot query IPGeolocation API on a database plan subscription."
pausedSubscription:
summary: Subscription paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at support@ipgeolocation.io"
freePlanLang:
summary: Non-English language on Free plan
value:
message: "This 'de' lang is not supported for your current subscription. Please use 'en' as the default language or upgrade your subscription to use this feature."
"404":
description: |
Not Found. Returned for one of the following reasons:
- If the IPv4 or IPv6 address is passed as a path variable instead
of a URL parameter (`ip=`).
- If the wrong endpoint is called that does not exist in the API.
Note: unlike the single-date `/v3/astronomy` endpoint, an invalid or
unresolvable `location` address on this endpoint returns HTTP 400,
not 404 (see the `invalidLocation` example under the 400 response).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
wrongEndpoint:
summary: Incorrect or non-existent endpoint
value:
message: "No endpoint GET /v3/astronomy-invalid."
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
components:
responses:
MethodNotAllowed:
description: |
Method Not Allowed. Returned when an unsupported HTTP method is used
to call an endpoint.
Only GET and POST methods are supported:
- `GET` is allowed for the `ipgeo` endpoint.
- `POST` is allowed for the `ipgeo-bulk` endpoint.
Any other HTTP method, or using the correct method on the wrong endpoint,
results in HTTP 405.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
getNotAllowedForBulk:
summary: GET used on bulk endpoint
value:
message: "Request method 'GET' is not supported"
postNotAllowedForSingle:
summary: POST used on single lookup endpoint
value:
message: "Request method 'POST' is not supported"
unsupportedMethod:
summary: Unsupported HTTP method
value:
message: "Request method is not supported"
PayloadTooLarge:
description: |
Payload too large. Returned by the edge proxy (nginx) when raw POST body size
exceeds configured limits before the request reaches the application.
This status is based on payload byte size, not on the number of IP entries. It
can occur even when `ips` contains only one very large value.
If both conditions apply (oversized body and `ips` count > 50,000), HTTP 413 may
be returned first because edge validation runs before application-level checks.
content:
text/html:
schema:
type: string
example: |
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 credit allowance has been reached for a Free subscription.
- The API credit allowance has been reached for a Paid subscription with
status 'past due', 'deleted', or 'trial expired'.
- The surcharge (overage) credit limit has been reached for the subscribed plan.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
usageLimitReached:
summary: API credit limit reached
value:
message: "You have exceeded the limit of PLAN_USAGE_LIMIT API credits per PLAN_INTERVAL for your subscribed PLAN plan. Please wait for your credits to reset, enable overage, or upgrade your plan to continue using IPGeolocation API without interruption."
surchargeLimitReached:
summary: Surcharge usage limit reached
value:
message: "You have reached the surcharge amount limit of PLAN_USAGE_LIMIT_AND_SURCHARGE_LIMIT on your subscribed PLAN plan. Please wait for your credits to reset, enable a higher surcharge limit, or upgrade your plan to continue using IPGeolocation API without interruption."
ClientClosedRequest:
description: |
The client closed the connection before the server finished processing the
request. This usually happens when the client sets a very short request or
connection timeout. Increase the timeout on the client side.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "Client closed the request before the server could respond."
InternalServerError:
description: |
Internal Server Error. The server encountered an unexpected condition
that prevented it from fulfilling the request. If the issue persists,
contact support@ipgeolocation.io.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "Something went wrong on the server side."
BadGateway:
description: |
Bad Gateway. The API server received an invalid response from an upstream
server while processing the request. This is usually temporary.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "Upstream service error. Please try again later."
ServiceUnavailable:
description: |
Service Unavailable. The API is temporarily unavailable due to maintenance
or overload. Please try again later.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "Service temporarily unavailable. Please try again later."
GatewayTimeout:
description: |
Gateway Timeout. The API server did not receive a timely response from
an upstream server.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "The server timed out while processing the request."
HttpVersionNotSupported:
description: |
HTTP Version Not Supported. The server does not support the HTTP protocol
version used in the request.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "HTTP version not supported."
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: apiKey
description: |
API key passed as the `apiKey` query parameter. Get yours from the
[IPGeolocation dashboard](https://app.ipgeolocation.io/). For client-side
usage, consider using Request Origin (CORS) authentication instead to
avoid exposing your key.
schemas:
ErrorResponse:
type: object
description: |
Returned for any non-200 response. Contains only a human-readable `message`.
Message text can vary by status and condition; examples in this spec are
representative, not exhaustive, and should not be treated as stable machine
codes.
required:
- message
properties:
message:
type: string
description: Human-readable explanation of what went wrong. Use HTTP status for control flow.
example: "Provided name, service or IP address '999.999.999.999' is not valid."
GetIpResponse:
type: object
xml:
name: LinkedHashMap
description: |
Response body for the Get IP endpoint. Contains only the caller's public
IP address.
required:
- ip
properties:
ip:
type: string
description: |
Public IP address of the client that called this endpoint. If called
from a server, this is the server's IP. If called from client-side
JavaScript, this is the visitor's public IP address.
example: "8.8.8.8"
BulkGeolocationRequest:
type: object
description: |
Request body for the bulk geolocation lookup. Contains a single `ips` field
with an array of IP addresses or domain names to look up.
required:
- ips
properties:
ips:
type: array
description: |
Array of IPv4 addresses, IPv6 addresses, or domain names to look up.
Must not be empty. Maximum 50,000 entries per request. Each entry is
resolved independently, so you can mix IPv4, IPv6, and domains freely.
minItems: 1
maxItems: 50000
items:
type: string
example:
- "8.8.8.8"
- "91.128.103.196"
- "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
- "ipgeolocation.io"
BulkGeolocationResponseItem:
description: |
A single element in the bulk lookup response array. Each element is either a
full geolocation object or an error object containing only `message`.
discriminator:
propertyName: type
mapping:
success: "#/components/schemas/BulkGeolocationSuccessItem"
error: "#/components/schemas/BulkGeolocationErrorItem"
oneOf:
- $ref: "#/components/schemas/BulkGeolocationSuccessItem"
- $ref: "#/components/schemas/BulkGeolocationErrorItem"
BulkGeolocationSuccessItem:
type: object
required:
- ip
properties:
ip:
type: string
description: |
The resolved IP address for this bulk entry. For direct IPv4/IPv6 input,
this matches the submitted value (normalized). For domain input, this is
the resolved A/AAAA IP.
example: "8.8.8.8"
domain:
type: string
description: |
Present only when the submitted `ips` entry was a domain name.
Contains the original domain input exactly as submitted.
example: "ipgeolocation.io"
hostname:
type: string
description: |
Reverse-DNS hostname for the IP. Only present when one of the hostname
`include` options is used.
example: "dns.google"
location:
$ref: "#/components/schemas/IPGeoLocation"
country_metadata:
$ref: "#/components/schemas/IPGeoCountryMetadata"
network:
$ref: "#/components/schemas/IPGeoNetwork"
currency:
$ref: "#/components/schemas/IPGeoCurrency"
asn:
$ref: "#/components/schemas/IPGeoAsn"
company:
$ref: "#/components/schemas/IPGeoCompany"
security:
$ref: "#/components/schemas/IPGeoSecurity"
abuse:
$ref: "#/components/schemas/IPGeoAbuse"
time_zone:
$ref: "#/components/schemas/IPGeoTimeZone"
user_agent:
$ref: "#/components/schemas/IPGeoUserAgent"
BulkGeolocationErrorItem:
type: object
description: |
Error object returned for an invalid entry in the bulk lookup request. Contains only
a `message` field. Note: unlike success entries, error entries do NOT include the
original `ip` field, so the only way to correlate errors to inputs is by array
index. The response array preserves the same order as the request `ips` array.
required:
- message
properties:
message:
type: string
description: Human-readable error for the specific bulk entry.
example: "Provided name, service or IP address 'invalid-ip' is not valid."
IpGeolocationResponse:
type: object
xml:
name: LinkedHashMap
description: |
The top-level response object for a single IP lookup. Where fields and nested
objects appear depends on your plan (free vs. paid) and the `include`, `fields`,
and `excludes` parameters. The `ip` field is always present.
required:
- ip
properties:
ip:
type: string
description: |
The looked-up IP address. If a domain was queried, this is the resolved IP.
If no `ip` parameter was sent, this is the caller's public IP.
example: "91.128.103.196"
domain:
type: string
description: |
Present only when the `ip` query parameter contained a domain name. Mirrors
the domain value from the request.
example: "ipgeolocation.io"
hostname:
type: string
description: |
Reverse-DNS hostname for the IP. Returned only when one of the hostname
`include` options is used (`hostname`, `liveHostname`, or
`hostnameFallbackLive`). If no hostname can be resolved, this field contains
the IP address itself.
example: "host197.lightwavenetworks.com"
location:
$ref: "#/components/schemas/IPGeoLocation"
country_metadata:
$ref: "#/components/schemas/IPGeoCountryMetadata"
network:
$ref: "#/components/schemas/IPGeoNetwork"
currency:
$ref: "#/components/schemas/IPGeoCurrency"
asn:
$ref: "#/components/schemas/IPGeoAsn"
company:
$ref: "#/components/schemas/IPGeoCompany"
security:
$ref: "#/components/schemas/IPGeoSecurity"
abuse:
$ref: "#/components/schemas/IPGeoAbuse"
time_zone:
$ref: "#/components/schemas/IPGeoTimeZone"
user_agent:
$ref: "#/components/schemas/IPGeoUserAgent"
IPGeoLocation:
type: object
description: Geographic location data for the IP address.
properties:
continent_code:
type: string
description: Two-letter continent code (e.g. `EU`, `NA`, `AS`).
example: "EU"
continent_name:
type: string
description: Full continent name.
example: "Europe"
country_code2:
type: string
description: ISO 3166-1 alpha-2 country code.
example: "SE"
country_code3:
type: string
description: ISO 3166-1 alpha-3 country code.
example: "SWE"
country_name:
type: string
description: Common country name.
example: "Sweden"
country_name_official:
type: string
description: Official country name as recognized by the UN.
example: "Kingdom of Sweden"
country_capital:
type: string
description: Capital city of the country.
example: "Stockholm"
state_prov:
type: string
description: State, province, or top-level administrative region.
example: "Stockholms län"
state_code:
type: string
description: ISO 3166-2 state or province code.
example: "SE-AB"
district:
type: string
description: District, county, or second-level administrative division.
example: "Stockholm"
city:
type: string
description: City name.
example: "Stockholm"
locality:
type: string
description: |
Locality or neighborhood. May be the same as `city`. Only present when
`include=geo_accuracy` or `include=*` is used.
example: "Stockholm"
accuracy_radius:
type: string
description: |
Estimated accuracy radius in kilometers around `latitude` and `longitude`.
Only present when `include=geo_accuracy` or `include=*` is used.
example: "4.395"
confidence:
type: string
description: |
Confidence level for the accuracy radius. Possible values: `high`, `medium`,
`low`. Only present when `include=geo_accuracy` or `include=*` is used.
enum:
- high
- medium
- low
example: "high"
dma_code:
type: string
description: |
Nielsen Designated Market Area code. Only populated for US-based IPs.
Present when `include=dma_code` or `include=*` is used. Empty string for
non-US IPs.
example: "504"
zipcode:
type: string
description: Postal or ZIP code.
example: "164 40"
latitude:
type: string
description: Latitude in decimal degrees (WGS 84).
example: "59.40510"
longitude:
type: string
description: Longitude in decimal degrees (WGS 84).
example: "17.95510"
is_eu:
type: boolean
description: Whether the country is a member of the European Union.
example: true
country_flag:
type: string
format: uri
description: URL to a 64x64 PNG of the country flag.
example: "https://ipgeolocation.io/static/flags/se_64.png"
geoname_id:
type: string
description: GeoNames identifier for the location.
example: "9972319"
country_emoji:
type: string
description: Unicode flag emoji for the country.
example: "\U0001F1F8\U0001F1EA"
IPGeoCountryMetadata:
type: object
description: Telephone, TLD, and language information for the country.
properties:
calling_code:
type: string
description: International dialing code with leading `+`.
example: "+46"
tld:
type: string
description: Country-code top-level domain.
example: ".se"
languages:
type: array
description: |
IETF language tags spoken in the country, ordered by prevalence.
items:
type: string
example:
- "sv-SE"
- "se"
- "sma"
- "fi-SE"
IPGeoNetwork:
type: object
description: |
Network routing information for the IP. Included by default on paid plans.
Not available on the free plan.
properties:
connection_type:
type: string
description: |
Type of network connection for this IP. Known values: `DSL`, `Cable`,
`Fiber`, `Mobile`, `Wireless`, `Dial-Up/ISDN`, `Satellite`. Empty string
when the type cannot be determined.
example: ""
route:
type: string
description: BGP route prefix in CIDR notation.
example: "91.128.0.0/14"
is_anycast:
type: boolean
description: Whether the IP is part of an anycast network.
example: false
is_cdn:
type: boolean
description: |
Whether the IP is part of a Content Delivery Network (CDN) or cloud
provider network.
example: false
cdn_provider_name:
type: string
description: |
Name of the CDN provider when `is_cdn` is `true` (e.g. `Cloudflare`).
Empty string otherwise.
example: ""
IPGeoCurrency:
type: object
description: Local currency of the country where the IP is located.
properties:
code:
type: string
description: ISO 4217 currency code.
example: "SEK"
name:
type: string
description: Currency name.
example: "Swedish Krona"
symbol:
type: string
description: Currency symbol.
example: "kr"
IPGeoAsn:
type: object
description: |
Autonomous System Number details for the IP. Free plans receive `as_number`,
`organization`, and `country` only. Paid plans also receive `type`, `domain`,
`date_allocated`, and `rir`.
properties:
as_number:
type: string
description: AS number prefixed with `AS` (e.g. `AS1257`).
example: "AS1257"
organization:
type: string
description: Name of the organization that owns the ASN.
example: "Tele2 Sverige AB"
country:
type: string
description: ISO 3166-1 alpha-2 country where the ASN is registered.
example: "SE"
type:
type: string
description: |
Organization type. Values: `ISP`, `HOSTING`, `BUSINESS`, `EDUCATION`,
`GOVERNMENT`. Paid plans only.
example: "ISP"
domain:
type: string
description: Primary domain of the ASN holder. Paid plans only.
example: "tele2.com"
date_allocated:
type: string
description: |
Date when the ASN was allocated, in `YYYY-MM-DD` format (e.g.
`2024-12-13`). Paid plans only.
example: "2024-12-13"
rir:
type: string
description: |
Regional Internet Registry (RIR) that allocated the ASN. Possible values include `RIPE`, `ARIN`, `APNIC`, `LACNIC`, `AFRINIC`, etc.
example: "RIPE"
IPGeoCompany:
type: object
description: |
Company or organization operating the IP range. Included by default on paid
plans. Not available on the free plan.
properties:
name:
type: string
description: Company or organization name.
example: "Tele2 Sverige AB"
type:
type: string
description: |
Company category. Documented values: `ISP`, `HOSTING`, `BUSINESS`,
`EDUCATION`, `GOVERNMENT`. All uppercase, consistent with `asn.type`.
May be an empty string when the company type cannot be determined.
example: "ISP"
domain:
type: string
description: Primary domain of the company.
example: "tele2.com"
IPGeoSecurity:
type: object
description: |
Threat intelligence and anonymization signals for the IP. Only returned when
`include=security` or `include=*` is used. Costs 2 additional credits.
properties:
threat_score:
type: number
description: |
Overall threat score from 0 (clean) to 100 (high risk). Aggregated from
all the individual signals below.
minimum: 0
maximum: 100
example: 80
is_tor:
type: boolean
description: Whether the IP is a known Tor exit node.
example: false
is_proxy:
type: boolean
description: Whether the IP belongs to a known proxy service.
example: true
proxy_provider_names:
type: array
description: Names of proxy providers associated with this IP, if any.
items:
type: string
example:
- "Zyte Proxy"
proxy_confidence_score:
type: number
description: |
Confidence that this IP is a proxy, from 0 to 100. Only meaningful when
`is_proxy` is `true`.
minimum: 0
maximum: 100
example: 90
proxy_last_seen:
type: string
description: |
Date when this IP was last observed acting as a proxy, in `YYYY-MM-DD`
format. Empty string if never seen.
example: "2025-12-12"
is_residential_proxy:
type: boolean
description: Whether the IP is a known residential proxy.
example: true
is_vpn:
type: boolean
description: Whether the IP belongs to a known VPN provider.
example: true
vpn_provider_names:
type: array
description: Names of VPN providers associated with this IP, if any.
items:
type: string
example:
- "Nord VPN"
vpn_confidence_score:
type: number
description: |
Confidence that this IP is a VPN endpoint, from 0 to 100. Only meaningful
when `is_vpn` is `true`.
minimum: 0
maximum: 100
example: 90
vpn_last_seen:
type: string
description: |
Date when this IP was last observed as a VPN endpoint, in `YYYY-MM-DD`
format. Empty string if never seen.
example: "2026-01-19"
is_relay:
type: boolean
description: Whether the IP is part of a known relay network (e.g. iCloud Private Relay).
example: false
relay_provider_name:
type: string
description: Name of the relay provider, if any. Empty string if not a relay.
example: ""
is_anonymous:
type: boolean
description: |
Whether the IP is associated with any anonymization method (VPN, proxy,
Tor, or relay).
example: true
is_known_attacker:
type: boolean
description: Whether the IP has been flagged in known attacker or threat feeds.
example: true
is_bot:
type: boolean
description: Whether the IP is associated with known bot activity.
example: false
bot_confidence_score:
type: number
description: |
Confidence that this IP is associated with bot activity, from 0 to 100.
Only populated when `is_bot` is `true`; otherwise `0`.
minimum: 0
maximum: 100
example: 0
bot_operator_name:
type: string
description: |
Organization operating the bot. Typically only populated for known good
bots (see `is_known_good_bot`). Empty string otherwise.
example: ""
bot_type:
type: string
description: |
Type of bot activity detected, when available (e.g. `search_engine`,
`ai_crawler`, `scraper`, `exploit`). Empty string if unknown.
example: ""
externalDocs:
description: bot_type values reference
url: "https://ipgeolocation.io/documentation/ip-security-api.html#bot-type-values"
is_known_good_bot:
type: boolean
description: |
Whether the bot is declared and verifiable, such as a search engine
crawler, uptime monitor, or security scanner.
example: false
bot_last_seen:
type: string
description: |
Date when this IP was last observed engaging in bot activity, in
`YYYY-MM-DD` format. Empty string if never seen.
example: ""
is_spam:
type: boolean
description: Whether the IP is listed in spam databases.
example: false
is_cloud_provider:
type: boolean
description: Whether the IP belongs to a cloud hosting or data center provider.
example: true
cloud_provider_name:
type: string
description: Name of the cloud provider, if applicable. Empty string otherwise.
example: "Packethub S.A."
is_corporate_gateway:
type: boolean
description: |
Whether the IP is an egress address of a secure web gateway (SWG),
security service edge (SSE), or secure access service edge (SASE) product.
example: false
corporate_gateway_type:
type: string
description: |
Type of corporate gateway service, when available (`secure_web_gateway`
or `browser_isolation`). Empty string if unknown.
example: ""
externalDocs:
description: corporate_gateway_type values reference
url: "https://ipgeolocation.io/documentation/ip-security-api.html#corporate-gateway-type-values"
corporate_gateway_provider_name:
type: string
description: |
Name of the corporate gateway provider, when available. Empty string
otherwise.
example: ""
IPGeoAbuse:
type: object
description: |
Abuse contact information for the network that owns this IP. Only returned when
`include=abuse` or `include=*` is used. Costs 1 additional credit.
properties:
route:
type: string
description: BGP route prefix this abuse contact is responsible for, in CIDR notation.
example: "91.128.0.0/14"
country:
type: string
description: ISO 3166-1 alpha-2 country of the abuse contact. May be empty.
example: "SE"
name:
type: string
description: Name of the abuse contact person or team.
example: "Swipnet Staff"
organization:
type: string
description: Organization name of the abuse contact. May be empty.
example: ""
kind:
type: string
description: |
Contact type from registry data. Values include `group`, `individual`.
example: "group"
address:
type: string
description: Postal address of the abuse contact. Returned as a plain comma-separated string.
example: "Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN"
emails:
type: array
description: Email addresses for reporting abuse.
items:
type: string
format: email
example:
- "abuse@tele2.com"
phone_numbers:
type: array
description: Phone numbers for the abuse contact.
items:
type: string
example:
- "+46 8 5626 42 10"
IPGeoTimeZone:
type: object
description: Timezone information for the geographic location of the IP.
properties:
name:
type: string
description: IANA timezone identifier.
example: "Europe/Stockholm"
offset:
type: number
format: float
description: UTC offset in hours (without DST).
example: 1
offset_with_dst:
type: number
format: float
description: |
Current UTC offset in hours, accounting for DST if active. Same as
`offset` when DST is not in effect.
example: 1
current_time:
type: string
description: |
Current local time at the IP's location. Observed formats include
`YYYY-MM-DDTHH:mm:ss±ZZZZ` and `YYYY-MM-DD HH:mm:ss.SSS±ZZZZ`.
example: "2026-02-13 09:19:24.410+0100"
current_time_unix:
type: number
format: float
description: Current time as a Unix timestamp with millisecond precision.
example: 1770970764.41
current_tz_abbreviation:
type: string
description: |
Abbreviation of the timezone currently in effect (may be standard or DST).
example: "CET"
current_tz_full_name:
type: string
description: Full name of the timezone currently in effect.
example: "Central European Standard Time"
standard_tz_abbreviation:
type: string
description: Abbreviation of the standard (non-DST) timezone.
example: "CET"
standard_tz_full_name:
type: string
description: Full name of the standard (non-DST) timezone.
example: "Central European Standard Time"
is_dst:
type: boolean
description: Whether Daylight Saving Time is currently active.
example: false
dst_savings:
type: number
format: float
description: |
DST offset in hours applied on top of the standard offset when DST is
active. `0` means no DST shift (either DST is not active or does not exist).
example: 0
dst_exists:
type: boolean
description: Whether this timezone observes Daylight Saving Time at all.
example: true
dst_tz_abbreviation:
type: string
description: |
Abbreviation of the DST timezone. Empty string if DST is not observed.
example: "CEST"
dst_tz_full_name:
type: string
description: |
Full name of the DST timezone. Empty string if DST is not observed.
example: "Central European Summer Time"
dst_start:
description: |
Start DST transition details. When `dst_exists` is `false`, this is
returned as an empty object with no properties.
oneOf:
- $ref: "#/components/schemas/IPGeoDstTransition"
- type: object
maxProperties: 0
dst_end:
description: |
End DST transition details. When `dst_exists` is `false`, this is
returned as an empty object with no properties.
oneOf:
- $ref: "#/components/schemas/IPGeoDstTransition"
- type: object
maxProperties: 0
IPGeoDstTransition:
type: object
description: |
Details about a DST transition (start or end). Only present when `dst_exists`
is `true`. When `dst_exists` is `false`, `dst_start` and `dst_end` are
returned as empty objects with no properties.
properties:
utc_time:
type: string
description: UTC time of the transition, formatted as `YYYY-MM-DD TIME HH:mm`.
example: "2026-03-29 TIME 01:00"
duration:
type: string
description: |
Clock shift direction and amount (e.g. `+1.00H` for spring forward,
`-1.00H` for fall back).
example: "+1.00H"
gap:
type: boolean
description: |
Whether this transition creates a gap in local time (clocks jump forward).
`true` for DST start, `false` for DST end.
example: true
date_time_after:
type: string
description: Local time immediately after the transition.
example: "2026-03-29 TIME 03:00"
date_time_before:
type: string
description: Local time immediately before the transition.
example: "2026-03-29 TIME 02:00"
overlap:
type: boolean
description: |
Whether this transition creates an overlap in local time (clocks fall back,
so the same local time occurs twice). `true` for DST end, `false` for DST
start.
example: false
IPGeoUserAgent:
type: object
description: |
Parsed User-Agent information. Only returned when `include=user_agent` or
`include=*` is used. The API parses the `User-Agent` header from the request.
For server-side usage, forward your visitor's User-Agent string in the header.
properties:
user_agent_string:
type: string
description: The raw User-Agent string that was parsed.
example: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0"
name:
type: string
description: Detected browser or client name.
example: "Edge"
type:
type: string
description: |
Client type classification. Common values: `Browser`, `Robot`,
`Mobile Browser`, `Library`.
example: "Browser"
version:
type: string
description: Full version string of the detected client.
example: "143"
version_major:
type: string
description: Major version number of the detected client.
example: "143"
device:
$ref: "#/components/schemas/IPGeoUserAgentDevice"
engine:
$ref: "#/components/schemas/IPGeoUserAgentEngine"
operating_system:
$ref: "#/components/schemas/IPGeoUserAgentOperatingSystem"
IPGeoUserAgentDevice:
type: object
description: Device information extracted from the User-Agent string.
properties:
name:
type: string
description: Device name or model.
example: "Linux Desktop"
type:
type: string
description: |
Device type. Common values: `Desktop`, `Smartphone`, `Tablet`, `Robot`,
`Smart TV`.
example: "Desktop"
brand:
type: string
description: Device manufacturer or brand. `Unknown` if not detectable.
example: "Unknown"
cpu:
type: string
description: CPU architecture if detectable (e.g. `Intel x86_64`, `ARM`). `Unknown` otherwise.
example: "Intel x86_64"
IPGeoUserAgentEngine:
type: object
description: Rendering engine information extracted from the User-Agent string.
properties:
name:
type: string
description: Engine name (e.g. `Blink`, `Gecko`, `WebKit`).
example: "Blink"
type:
type: string
description: Engine classification. Typically matches the client type.
example: "Browser"
version:
type: string
description: Full version of the rendering engine.
example: "143"
version_major:
type: string
description: Major version of the rendering engine.
example: "143"
IPGeoUserAgentOperatingSystem:
type: object
description: Operating system information extracted from the User-Agent string.
properties:
name:
type: string
description: OS name (e.g. `Windows`, `macOS`, `Linux`, `Android`, `iOS`, `Cloud`).
example: "Linux"
type:
type: string
description: |
OS type. Common values: `Desktop`, `Mobile`, `Tablet`, `Cloud`.
example: "Desktop"
version:
type: string
description: OS version. `??` when the version cannot be determined.
example: "??"
version_major:
type: string
description: OS major version. `??` when the version cannot be determined.
example: "??"
build:
type: string
description: OS build number. `??` when the build cannot be determined.
example: "??"
BulkSecurityRequest:
type: object
description: |
Request body for the bulk security lookup. Contains a single `ips` field
with an array of IP addresses to look up.
required:
- ips
properties:
ips:
type: array
description: |
Array of IPv4 addresses or IPv6 addresses to look up.
Must not be empty. Maximum 50,000 entries per request. Each entry is
resolved independently, so you can mix IPv4 and IPv6 freely.
minItems: 1
maxItems: 50000
items:
type: string
example:
- "8.8.8.8"
- "91.128.103.196"
- "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
BulkSecurityResponseItem:
description: |
A single element in the bulk lookup response array. Each element is either a
full security object or an error object containing only `message`.
oneOf:
- $ref: "#/components/schemas/BulkSecuritySuccessItem"
- $ref: "#/components/schemas/BulkSecurityErrorItem"
BulkSecuritySuccessItem:
type: object
required:
- ip
- security
properties:
ip:
type: string
description: IP address for this lookup result.
example: "2.56.188.34"
security:
$ref: "#/components/schemas/Security"
BulkSecurityErrorItem:
type: object
description: |
Error object returned for an invalid entry in the bulk lookup request. Contains only
a `message` field. Note: unlike success entries, error entries do NOT include the
original `ip` field, so the only way to correlate errors to inputs is by array
index. The response array preserves the same order as the request `ips` array.
required:
- message
properties:
message:
type: string
description: Human-readable error for the specific bulk entry.
example: "Provided IP address 'invalid-ip' is not valid."
IpSecurityResponse:
type: object
xml:
name: LinkedHashMap
required:
- ip
properties:
ip:
type: string
description: IP address used for the lookup.
example: "2.56.188.34"
security:
$ref: "#/components/schemas/Security"
Security:
type: object
description: |
Threat intelligence and anonymization signals for the IP. Costs 2 credits.
properties:
threat_score:
type: number
description: |
Overall threat score from 0 (clean) to 100 (high risk). Aggregated from
all the individual signals below.
minimum: 0
maximum: 100
example: 80
is_tor:
type: boolean
description: Whether the IP is a known Tor exit node.
example: false
is_proxy:
type: boolean
description: Whether the IP belongs to a known proxy service.
example: true
proxy_provider_names:
type: array
description: Names of proxy providers associated with this IP, if any.
items:
type: string
example:
- "Zyte Proxy"
proxy_confidence_score:
type: number
description: |
Confidence that this IP is a proxy, from 0 to 100. Only meaningful when
`is_proxy` is `true`.
minimum: 0
maximum: 100
example: 90
proxy_last_seen:
type: string
description: |
Date when this IP was last observed acting as a proxy, in `YYYY-MM-DD`
format. Empty string if never seen.
example: "2025-12-12"
is_residential_proxy:
type: boolean
description: Whether the IP is a known residential proxy.
example: true
is_vpn:
type: boolean
description: Whether the IP belongs to a known VPN provider.
example: true
vpn_provider_names:
type: array
description: Names of VPN providers associated with this IP, if any.
items:
type: string
example:
- "Nord VPN"
vpn_confidence_score:
type: number
description: |
Confidence that this IP is a VPN endpoint, from 0 to 100. Only meaningful
when `is_vpn` is `true`.
minimum: 0
maximum: 100
example: 90
vpn_last_seen:
type: string
description: |
Date when this IP was last observed as a VPN endpoint, in `YYYY-MM-DD`
format. Empty string if never seen.
example: "2026-01-19"
is_relay:
type: boolean
description: Whether the IP is part of a known relay network (e.g. iCloud Private Relay).
example: false
relay_provider_name:
type: string
description: Name of the relay provider, if any. Empty string if not a relay.
example: ""
is_anonymous:
type: boolean
description: |
Whether the IP is associated with any anonymization method (VPN, proxy,
Tor, or relay).
example: true
is_known_attacker:
type: boolean
description: Whether the IP has been flagged in known attacker or threat feeds.
example: true
is_bot:
type: boolean
description: Whether the IP is associated with known bot activity.
example: false
bot_confidence_score:
type: number
description: |
Confidence that this IP is associated with bot activity, from 0 to 100.
Only populated when `is_bot` is `true`; otherwise `0`.
minimum: 0
maximum: 100
example: 0
bot_operator_name:
type: string
description: |
Organization operating the bot. Typically only populated for known good
bots (see `is_known_good_bot`). Empty string otherwise.
example: ""
bot_type:
type: string
description: |
Type of bot activity detected, when available (e.g. `search_engine`,
`ai_crawler`, `scraper`, `exploit`). Empty string if unknown.
example: ""
externalDocs:
description: bot_type values reference
url: "https://ipgeolocation.io/documentation/ip-security-api.html#bot-type-values"
is_known_good_bot:
type: boolean
description: |
Whether the bot is declared and verifiable, such as a search engine
crawler, uptime monitor, or security scanner.
example: false
bot_last_seen:
type: string
description: |
Date when this IP was last observed engaging in bot activity, in
`YYYY-MM-DD` format. Empty string if never seen.
example: ""
is_spam:
type: boolean
description: Whether the IP is listed in spam databases.
example: false
is_cloud_provider:
type: boolean
description: Whether the IP belongs to a cloud hosting or data center provider.
example: true
cloud_provider_name:
type: string
description: Name of the cloud provider, if applicable. Empty string otherwise.
example: "Packethub S.A."
is_corporate_gateway:
type: boolean
description: |
Whether the IP is an egress address of a secure web gateway (SWG),
security service edge (SSE), or secure access service edge (SASE) product.
example: false
corporate_gateway_type:
type: string
description: |
Type of corporate gateway service, when available (`secure_web_gateway`
or `browser_isolation`). Empty string if unknown.
example: ""
externalDocs:
description: corporate_gateway_type values reference
url: "https://ipgeolocation.io/documentation/ip-security-api.html#corporate-gateway-type-values"
corporate_gateway_provider_name:
type: string
description: |
Name of the corporate gateway provider, when available. Empty string
otherwise.
example: ""
ASNLookupResponse:
type: object
xml:
name: LinkedHashMap
description: |
Response returned by the ASN Lookup API.
Contains the queried IP address (when an IP lookup is performed) and
the ASN information associated with the network responsible for routing
that IP address.
When the lookup is performed using the `asn` parameter, the `ip` field
is not included in the response.
properties:
ip:
type: string
description: |
The IP address for which ASN details are returned. This field appears
only when the lookup is performed using an IP address.
example: "49.12.0.0"
asn:
$ref: "#/components/schemas/ASN"
ASN:
type: object
description: |
ASN information describing the Autonomous System responsible for routing
the queried IP address or the specified ASN. Costs 1 credit.
properties:
as_number:
type: string
description: Complete Autonomous System Number that was looked up.
example: "AS24940"
organization:
type: string
description: Name of the organization to which the ASN is assigned.
example: "Hetzner Online GmbH"
country:
type: string
description: ISO 3166-1 alpha-2 country code where the ASN is registered.
example: "DE"
asn_name:
type: string
description: Official ASN handle.
example: "HETZNER-AS"
type:
type: string
description: |
ASN category. Possible values include `ISP`, `HOSTING`, `BUSINESS`,
`EDUCATION`, or `GOVERNMENT` when available.
example: "HOSTING"
domain:
type: string
description: Domain associated with the ASN.
example: "hetzner.com"
date_allocated:
type: string
description: Date when the ASN was originally allocated.
example: "2002-06-03"
rir:
type: string
description: |
Regional Internet Registry that allocated the ASN.
Examples include `RIPE`, `ARIN`, `APNIC`, `LACNIC`, `AFRINIC`, etc.
example: "RIPE"
allocation_status:
type: string
description: Current allocation status of the ASN.
example: "ASSIGNED"
num_of_ipv4_routes:
type: string
description: Number of IPv4 prefixes announced by this ASN.
example: "84"
num_of_ipv6_routes:
type: string
description: Number of IPv6 prefixes announced by this ASN.
example: "6"
peers:
type: array
description: Directly connected peer ASNs.
items:
$ref: "#/components/schemas/ASNConnection"
downstreams:
type: array
description: Downstream (customer) ASNs connected to this ASN.
items:
$ref: "#/components/schemas/ASNConnection"
upstreams:
type: array
description: Upstream provider ASNs used for internet connectivity.
items:
$ref: "#/components/schemas/ASNConnection"
routes:
type: array
description: IPv4 and IPv6 prefixes announced by this ASN.
items:
type: string
example:
- "192.76.177.0/24"
- "2607:f600::/32"
whois_response:
type: string
description: Raw WHOIS registry record text returned for the ASN.
example: "ASNumber: 24940\nOrgName: Hetzner Online GmbH\nCountry: DE"
ASNConnection:
type: object
description: |
Represents a connected Autonomous System such as a peer,
upstream provider, or downstream customer.
properties:
as_number:
type: string
description: Autonomous System Number of the connected network.
example: "AS3356"
description:
type: string
description: Name or description of the connected network operator.
example: "Level 3 Parent, LLC"
country:
type: string
description: Country code of the connected ASN.
example: "US"
AbuseLookupResponse:
type: object
xml:
name: LinkedHashMap
description: |
Response returned by the IP Abuse Contact API.
Contains the queried IP address and the abuse contact information
associated with the network responsible for that IP.
The `ip` field is always present. The `abuse` object may be partially
populated depending on available registry data and field filtering.
required:
- ip
- abuse
properties:
ip:
type: string
description: |
The IP address for which abuse contact details are returned.
example: "1.0.0.0"
abuse:
$ref: "#/components/schemas/Abuse"
Abuse:
type: object
description: |
Abuse contact information for the network that owns this IP. Costs 1 credit.
properties:
route:
type: string
description: BGP route prefix this abuse contact is responsible for, in CIDR notation.
example: "91.128.0.0/14"
country:
type: string
description: ISO 3166-1 alpha-2 country of the abuse contact. May be empty.
example: "SE"
name:
type: string
description: Name of the abuse contact person or team.
example: "Swipnet Staff"
organization:
type: string
description: Organization name of the abuse contact. May be empty.
example: ""
kind:
type: string
description: |
Contact type from registry data. Values include `group`, `individual`.
example: "group"
address:
type: string
description: Postal address of the abuse contact. Returned as a plain comma-separated string.
example: "Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN"
emails:
type: array
description: Email addresses for reporting abuse.
items:
type: string
format: email
example:
- "abuse@tele2.com"
phone_numbers:
type: array
description: Phone numbers for the abuse contact.
items:
type: string
example:
- "+46 8 5626 42 10"
TimezoneLookupResponse:
type: object
xml:
name: LinkedHashMap
description: |
Response returned by the Timezone Lookup API.
Contains timezone information for the requested identifier such as a
timezone name, IP address, geographic coordinates, location address,
airport code (IATA/ICAO), or UN/LOCODE.
Depending on the lookup method used, additional contextual objects may
be returned:
- `ip` appears when the lookup is performed using an IP address or when
no parameters are provided (caller IP lookup).
- `location` appears when the lookup is performed using an IP address
or location address.
- `airport_details` appears when the lookup is performed using
`iata_code` or `icao_code`.
- `lo_code_details` appears when the lookup is performed using
`lo_code`.
The `time_zone` object is always present in the response.
properties:
ip:
type: string
description: |
The IP address used to determine the timezone. This field appears
only when the lookup is performed using an IP address or when the
API resolves the caller's IP automatically.
example: "8.8.8.8"
location:
description: |
Geolocation details for the resolved location.
When the lookup is performed using the `ip` parameter (or the
caller's IP is resolved automatically), this is the IP-based
shape (`TimezoneLocationFromIp`). When the lookup is performed
using the `location` parameter, this is the smaller,
geocoded-address shape (`TimezoneLocationFromName`).
oneOf:
- $ref: "#/components/schemas/TimezoneLocationFromIp"
- $ref: "#/components/schemas/TimezoneLocationFromName"
airport_details:
$ref: "#/components/schemas/TimezoneAirportDetails"
lo_code_details:
$ref: "#/components/schemas/TimezoneLocodeDetails"
time_zone:
$ref: "#/components/schemas/Timezone"
TimeConversionResponse:
type: object
xml:
name: LinkedHashMap
description: |
Response returned by the Timezone Conversion API.
Contains the original timestamp, the converted timestamp in the
destination timezone, and the time difference between the two
locations or timezones.
The conversion can be performed using timezone names, geographic
coordinates, location addresses, airport codes (IATA/ICAO),
or UN/LOCODE identifiers.
properties:
original_time:
type: string
description: |
The original timestamp before conversion. If the `time`
parameter is omitted, this value represents the current
time at the source location.
example: "2024-12-08 11:00"
converted_time:
type: string
description: |
The converted timestamp in the destination timezone.
example: "2024-12-08 18:30:00"
diff_hour:
type: number
format: float
description: |
Time difference between the source and destination
timezones expressed in hours.
example: 7.5
diff_min:
type: number
description: |
Time difference between the source and destination
timezones expressed in minutes.
example: 450
Timezone:
type: object
description: |
Detailed timezone information for the requested location or identifier.
Contains timezone metadata such as UTC offset, daylight saving time (DST)
status, formatted timestamps, and DST transition information.
properties:
name:
type: string
description: IANA timezone identifier for the location.
example: "America/Los_Angeles"
offset:
type: number
format: float
description: Standard timezone offset from UTC in hours.
example: -8
offset_with_dst:
type: number
format: float
description: Timezone offset from UTC including daylight saving time.
example: -7
date:
type: string
description: Current date in `YYYY-MM-DD` format.
example: "2025-04-24"
date_time:
type: string
description: Current date and time in `YYYY-MM-DD HH:mm:ss` format.
example: "2025-04-24 11:30:12"
date_time_txt:
type: string
description: Human-readable date and time string.
example: "Thursday, April 24, 2025 11:30:12"
date_time_wti:
type: string
description: Date and time with timezone information.
example: "Thu, 24 Apr 2025 11:30:12 -0700"
date_time_ymd:
type: string
description: ISO-8601 formatted date and time with timezone offset.
example: "2025-04-24T11:30:12-0700"
current_time:
type: string
description: |
Current local time at the IP's location. Observed formats include
`YYYY-MM-DDTHH:mm:ss±ZZZZ` and `YYYY-MM-DD HH:mm:ss.SSS±ZZZZ`.
example: "2026-02-13 09:19:24.410+0100"
current_time_unix:
type: number
format: float
description: Unix timestamp representing the current date and time.
example: 1745519412.353
time_24:
type: string
description: Current local time in 24-hour format.
example: "11:30:12"
time_12:
type: string
description: Current local time in 12-hour format.
example: "11:30:12 AM"
week:
type: number
description: Week number of the current year.
example: 17
month:
type: number
description: Current month number.
example: 4
year:
type: number
description: Four-digit year.
example: 2025
year_abbr:
type: string
description: Two-digit abbreviated year.
example: "25"
current_tz_abbreviation:
type: string
description: Abbreviation of the timezone currently in effect.
example: "AEST"
current_tz_full_name:
type: string
description: Full name of the timezone currently in effect.
example: "Australian Eastern Standard Time"
standard_tz_abbreviation:
type: string
description: Standard (non-DST) timezone abbreviation.
example: "AEST"
standard_tz_full_name:
type: string
description: Full name of the standard timezone.
example: "Australian Eastern Standard Time"
is_dst:
type: boolean
description: Indicates whether daylight saving time is currently active.
dst_savings:
type: number
format: float
description: Number of hours added during daylight saving time.
dst_exists:
type: boolean
description: Indicates whether the region observes daylight saving time.
dst_tz_abbreviation:
type: string
description: Abbreviation used during daylight saving time.
example: "PDT"
dst_tz_full_name:
type: string
description: Full name used during daylight saving time.
example: "Pacific Daylight Time"
dst_start:
$ref: "#/components/schemas/TimezoneDSTTransition"
dst_end:
$ref: "#/components/schemas/TimezoneDSTTransition"
TimezoneDSTTransition:
type: object
description: |
Represents a daylight saving time transition event including the
moment when DST begins or ends.
properties:
utc_time:
type: string
description: UTC timestamp when the DST transition occurs.
example: "2026-03-29 TIME 01:00"
duration:
type: string
description: Time change applied during the transition.
example: "+1.00H"
gap:
type: boolean
description: Indicates whether an hour is skipped during the transition.
date_time_after:
type: string
description: Local date and time immediately after the DST change.
example: "2026-03-29 TIME 03:00"
date_time_before:
type: string
description: Local date and time immediately before the DST change.
example: "2026-03-29 TIME 02:00"
overlap:
type: boolean
description: Indicates whether clock time overlaps during the transition.
TimezoneLocationFromIp:
type: object
description: |
Geolocation information derived from an IP address lookup.
This object appears when the timezone lookup is performed using
the `ip` parameter, or when the API resolves the caller's IP
automatically.
It provides geographic details such as continent, country,
administrative regions, and coordinates used to determine the
corresponding timezone.
properties:
continent_code:
type: string
description: Two-letter continent code.
example: "EU"
continent_name:
type: string
description: Full name of the continent.
example: "Europe"
country_code2:
type: string
description: ISO 3166-1 alpha-2 country code.
example: "GB"
country_code3:
type: string
description: ISO 3166-1 alpha-3 country code.
example: "GBR"
country_name:
type: string
description: Common name of the country.
example: "United Kingdom"
country_name_official:
type: string
description: Official name of the country.
example: "United Kingdom of Great Britain and Northern Ireland"
is_eu:
type: boolean
description: Indicates whether the country is a member of the European Union.
state_prov:
type: string
description: State, province, or region name.
example: "England"
state_code:
type: string
description: Standardized state or region code.
example: "GB-ENG"
district:
type: string
description: District or administrative subdivision.
example: "Greater London"
city:
type: string
description: City name of the location.
example: "London"
zipcode:
type: string
description: ZIP or postal code of the location.
example: "SW1A"
latitude:
type: string
description: Latitude coordinate of the location.
example: "51.50002"
longitude:
type: string
description: Longitude coordinate of the location.
example: "-0.19244"
TimezoneLocationFromName:
type: object
description: |
Geolocation information derived from geocoding a free-text location
address.
This object appears when the timezone lookup is performed using the
`location` parameter. It has fewer fields than `TimezoneLocationFromIp`,
since it is produced by geocoding the provided address rather than
an IP lookup.
properties:
location_string:
type: string
description: Original location string provided in the request.
example: "London, UK"
country_name:
type: string
description: Common name of the country.
example: "United Kingdom"
state_prov:
type: string
description: State, province, or region name.
example: "England"
city:
type: string
description: City name of the location.
example: "London"
locality:
type: string
description: Smaller locality or neighborhood within the city.
example: "Westminster"
latitude:
type: string
description: Latitude coordinate of the location.
example: "51.50002"
longitude:
type: string
description: Longitude coordinate of the location.
example: "-0.19244"
TimezoneAirportDetails:
type: object
description: |
Airport information returned when the timezone lookup is performed
using `iata_code` or `icao_code`.
Contains metadata about the airport including its geographic
coordinates, country, and airport identifiers.
properties:
type:
type: string
description: Classification of the airport based on size and traffic.
example: "large_airport"
name:
type: string
description: Official name of the airport.
example: "Hartsfield Jackson Atlanta International Airport"
latitude:
type: string
description: Latitude coordinate of the airport.
example: "33.63670"
longitude:
type: string
description: Longitude coordinate of the airport.
example: "-84.42810"
elevation_ft:
type: number
description: Airport elevation above sea level measured in feet.
example: 1026
continent_code:
type: string
description: Two-letter continent code where the airport is located.
example: "NA"
country_code:
type: string
description: ISO 3166-1 alpha-2 country code.
example: "US"
state_code:
type: string
description: State or province code where the airport is located.
example: "US-GA"
city:
type: string
description: City served by the airport.
example: "Atlanta"
iata_code:
type: string
description: Three-letter IATA airport identifier.
example: "ATL"
icao_code:
type: string
description: Four-letter ICAO airport identifier.
example: "KATL"
faa_code:
type: string
description: FAA location identifier used primarily in the United States.
example: ""
TimezoneLocodeDetails:
type: object
description: |
City or logistics location information returned when the timezone
lookup is performed using a UN/LOCODE.
UN/LOCODE is a five-character identifier consisting of a two-letter
country code followed by a three-character location identifier.
properties:
lo_code:
type: string
description: UN/LOCODE representing the city or logistics location.
example: "DEBER"
city:
type: string
description: Name of the city associated with the UN/LOCODE.
example: "Berlin"
state_code:
type: string
description: State or region code of the location.
example: "BE"
country_code:
type: string
description: ISO 3166-1 alpha-2 country code.
example: "DE"
country_name:
type: string
description: Name of the country where the location exists.
example: "Germany"
location_type:
type: string
description: |
Type of facilities available at the location such as port,
rail terminal, road terminal, airport, or postal exchange.
example: "Port, Rail Terminal, Road Terminal, Airport, Postal Exchange"
latitude:
type: string
description: Latitude coordinate of the location.
example: "52.51667"
longitude:
type: string
description: Longitude coordinate of the location.
example: "13.38333"
UserAgentResponse:
type: object
description: |
Parsed user agent details including browser, device, layout engine, and
operating system information. Also indicates bots, crawlers, or malicious
user agent strings.
properties:
user_agent_string:
type: string
description: The raw user agent string that was parsed.
example: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"
name:
type: string
description: |
Name of the detected agent (e.g. browser name, bot name, or `"Hacker"`
if the string is malformed or contains injected scripts).
example: "Safari"
type:
type: string
description: |
Type of the detected user agent. See possible values in the documentation.
example: "Browser"
version:
type: string
description: Full version string of the detected agent.
example: "9.0.2"
version_major:
type: string
description: Major version of the detected agent.
example: "9"
device:
$ref: "#/components/schemas/Device"
engine:
$ref: "#/components/schemas/Engine"
operating_system:
$ref: "#/components/schemas/OperatingSystem"
Device:
type: object
description: Hardware device information extracted from the user agent string.
properties:
name:
type: string
description: Name of the device (e.g. model name or manufacturer).
example: "Apple Macintosh"
type:
type: string
description: |
Type of the device. See possible values in the documentation.
example: "Desktop"
brand:
type: string
description: Brand or manufacturer of the device.
example: "Apple"
cpu:
type: string
description: CPU architecture or model of the device. May be `"Unknown"`.
example: "Intel"
Engine:
type: object
description: Layout engine information extracted from the user agent string.
properties:
name:
type: string
description: Name of the layout engine (e.g. `"AppleWebKit"`, `"Blink"`, `"Gecko"`).
example: "AppleWebKit"
type:
type: string
description: |
Type of the layout engine. See possible values in the documentation.
example: "Browser"
version:
type: string
description: Full version string of the layout engine. May be `"??"` if unknown.
example: "601.3.9"
version_major:
type: string
description: Major version of the layout engine. May be `"??"` if unknown.
example: "601"
OperatingSystem:
type: object
description: Operating system information extracted from the user agent string.
properties:
name:
type: string
description: Name of the operating system.
example: "Mac OS"
type:
type: string
description: |
Type of the operating system. See possible values in the documentation.
example: "Desktop"
version:
type: string
description: Full version string of the operating system. May be `"??"` if unknown.
example: "10.11.2"
version_major:
type: string
description: Major version of the operating system. May be `"??"` if unknown.
example: "10.11"
build:
type: string
description: Build identifier of the operating system. May be `"??"` if unknown.
example: "??"
AstronomyLookupResponse:
type: object
description: |
Response returned by the single-date Astronomy Lookup API.
Contains a `location` object with geolocation details for the
resolved location, and an `astronomy` object with astronomical
event times and positional data for the requested date.
The `location` object structure varies based on the lookup method:
- Coordinate or location-based lookups return basic geographic fields.
- IP-based lookups return extended geolocation fields including
continent, country codes, district, and zipcode.
properties:
ip:
type: string
description: |
The IP address used for the astronomy lookup. Returned only when
the lookup is performed using the `ip` parameter or when the API
resolves the caller's IP automatically (no parameters provided).
example: "8.8.8.8"
location:
$ref: "#/components/schemas/Location"
astronomy:
$ref: "#/components/schemas/AstronomyData"
AstronomyTimeSeriesResponse:
type: object
description: |
Response returned by the Astronomy Time Series API.
Contains a `location` object and an `astronomy` array where each
element represents astronomical data for a single day within the
requested date range.
Note that real-time positional data (sun/moon altitude, azimuth,
distance, parallactic angle, illumination) is not included in time
series responses.
properties:
ip:
type: string
description: |
The IP address used for the astronomy lookup. Returned only when
the lookup is performed using the `ip` parameter or when the API
resolves the caller's IP automatically.
example: "8.8.8.8"
location:
$ref: "#/components/schemas/Location"
astronomy:
type: array
description: |
Array of daily astronomical records covering the requested date
range. Each entry contains event times for one calendar day.
items:
$ref: "#/components/schemas/AstronomyTimeSeriesEntry"
Location:
type: object
description: |
Geolocation information associated with the resolved location.
For coordinate-based or location-string lookups, only basic geographic
fields are returned (latitude, longitude, country, state, city, locality,
elevation).
For IP-based lookups, extended fields are also returned including
continent codes, country codes, district, zipcode, and other metadata.
properties:
location_string:
type: string
description: |
The location string provided in the request. Only present when the
`location` query parameter was used.
example: "New York, USA"
continent_code:
type: string
description: Two-letter continent code. Returned for IP-based lookups only.
example: "NA"
continent_name:
type: string
description: Full name of the continent. Returned for IP-based lookups only.
example: "North America"
country_code2:
type: string
description: |
ISO 3166-1 alpha-2 country code. Returned for IP-based lookups only.
example: "US"
country_code3:
type: string
description: |
ISO 3166-1 alpha-3 country code. Returned for IP-based lookups only.
example: "USA"
country_name:
type: string
description: Common name of the country.
example: "United States"
country_name_official:
type: string
description: |
Official name of the country. Returned for IP-based lookups only.
example: "United States of America"
is_eu:
type: boolean
description: |
Indicates whether the country is a member of the European Union.
Returned for IP-based lookups only.
state_prov:
type: string
description: State, province, or region name.
example: "New York"
state_code:
type: string
description: |
Standardized state or region code. Returned for IP-based lookups only.
example: "US-NY"
district:
type: string
description: |
District or administrative subdivision. Returned for IP-based
lookups only.
example: "Manhattan"
city:
type: string
description: City name of the location.
example: "New York"
locality:
type: string
description: Smaller locality or neighborhood within the city.
example: "Midtown West"
zipcode:
type: string
description: |
ZIP or postal code of the location. Returned for IP-based
lookups only.
example: "10001"
latitude:
type: string
format: float
description: Latitude coordinate of the resolved location.
example: "40.76473"
longitude:
type: string
format: float
description: Longitude coordinate of the resolved location.
example: "-74.00084"
elevation:
type: string
description: Elevation above sea level at the location, in meters.
example: "9"
TwilightPhase:
type: object
description: |
Twilight phase times for either the morning (pre-sunrise) or evening
(post-sunset) period.
Includes astronomical, nautical, and civil twilight windows, as well
as blue hour and golden hour windows commonly used in photography.
All times are in `HH:mm` format by default. When the `time_zone`
parameter is provided, times are returned as full date-time values
in `yyyy-MM-dd HH:mm` format.
properties:
astronomical_twilight_begin:
type: string
description: |
Start of astronomical twilight. In the morning, this marks the
end of night; in the evening, this marks the start of night sky.
example: "04:49"
astronomical_twilight_end:
type: string
description: End of astronomical twilight.
example: "05:21"
nautical_twilight_begin:
type: string
description: |
Start of nautical twilight, when the horizon first becomes visible.
example: "05:21"
nautical_twilight_end:
type: string
description: End of nautical twilight.
example: "05:53"
civil_twilight_begin:
type: string
description: |
Start of civil twilight, when there is enough light for outdoor
activities without artificial lighting.
example: "05:53"
civil_twilight_end:
type: string
description: End of civil twilight.
example: "06:20"
blue_hour_begin:
type: string
description: |
Start of the blue hour, a period of soft diffused light with a
blue color tone.
example: "05:42"
blue_hour_end:
type: string
description: End of the blue hour.
example: "06:03"
golden_hour_begin:
type: string
description: |
Start of the golden hour, a period of warm low-angle light
favored by photographers.
example: "06:03"
golden_hour_end:
type: string
description: End of the golden hour.
example: "06:57"
AstronomyData:
type: object
description: |
Astronomical data for the resolved location and requested date.
Includes event times for sunrise, sunset, moonrise, moonset,
twilight phases, golden hour, blue hour, solar noon, and
astronomical midnight, as well as real-time positional data
for the Sun and Moon at the current time of day.
All timestamp fields (except `current_time` and `day_length`) are
in `HH:mm` format by default. When the `time_zone` parameter is
provided, they are returned as full date-time values in
`yyyy-MM-dd HH:mm` format.
properties:
time_zone:
type: string
description: |
The IANA timezone identifier used for timestamp conversion.
This field appears only when the `time_zone` query parameter
was provided in the request.
example: "Europe/London"
date:
type: string
description: The date for which astronomical data is returned, in `yyyy-MM-dd` format.
example: "2026-03-18"
current_time:
type: string
description: |
Current local time at the resolved location in `HH:mm:ss.SSS` format.
Used as the reference time for real-time positional calculations
(altitude, azimuth, distance).
example: "10:15:00.000"
mid_night:
type: string
description: |
Astronomical midnight (nadir) for the given date, in `HH:mm` format.
example: "00:06"
night_end:
type: string
description: |
End of night / start of astronomical twilight in the morning,
in `HH:mm` format.
example: "04:49"
morning:
$ref: "#/components/schemas/TwilightPhase"
sunrise:
type: string
description: |
Time at which the sun rises at the resolved location, in `HH:mm`
format. Returns `"-:-"` if the sun does not rise on this date
(polar day or polar night).
example: "06:20"
sunset:
type: string
description: |
Time at which the sun sets at the resolved location, in `HH:mm`
format. Returns `"-:-"` if the sun does not set on this date
(polar day or polar night).
example: "19:00"
evening:
$ref: "#/components/schemas/TwilightPhase"
night_begin:
type: string
description: |
Start of night / end of astronomical twilight in the evening,
in `HH:mm` format.
example: "20:31"
sun_status:
type: string
description: |
Represents the current state of the sun relative to the horizon:
- `"-"` — Normal day with both sunrise and sunset occurring.
- `"Always above the twilight angle"` — The sun does not set
(perpetual daylight, e.g. polar summer).
- `"Always below the twilight angle"` — The sun does not rise
within the current 24-hour period (e.g. polar night).
example: "-"
solar_noon:
type: string
description: |
The time when the sun is at its highest point in the sky,
in `HH:mm` format.
example: "12:40"
day_length:
type: string
description: |
Total length of daylight for the date, from sunrise to sunset,
in `HH:mm` format. Returns `"-:-"` if sunrise or sunset does
not occur on this date (polar day or polar night).
example: "12:40"
sun_altitude:
type: number
format: float
description: |
The sun's altitude angle above the horizon at `current_time`,
measured in degrees. Negative values indicate the sun is below
the horizon.
example: 42.5
sun_distance:
type: number
format: float
description: |
Distance from Earth to the sun at `current_time`, in kilometers.
example: 148900000.0
sun_azimuth:
type: number
format: float
description: |
The azimuth angle of the sun at `current_time`, indicating its
compass direction in degrees (0° = North, 90° = East, etc.).
example: 150.3
moon_phase:
type: string
description: |
The current phase of the moon, indicating its position in the
lunar cycle.
enum:
- NEW_MOON
- WAXING_CRESCENT
- FIRST_QUARTER
- WAXING_GIBBOUS
- FULL_MOON
- WANING_GIBBOUS
- LAST_QUARTER
- WANING_CRESCENT
example: "WAXING_CRESCENT"
moonrise:
type: string
description: |
Time at which the moon rises at the resolved location, in `HH:mm`
format. Returns `"-:-"` if the moon does not rise on this date.
example: "08:45"
moonset:
type: string
description: |
Time at which the moon sets at the resolved location, in `HH:mm`
format. Returns `"-:-"` if the moon does not set on this date.
example: "22:10"
moon_status:
type: string
description: |
Represents the current state of the moon relative to the horizon:
- `"-"` — Normal day with both moonrise and moonset occurring.
- `"Always above the horizon"` — The moon does not set within
the current 24-hour period.
- `"Always below the horizon"` — The moon does not rise within
the current 24-hour period.
example: "-"
moon_altitude:
type: number
format: float
description: |
The moon's altitude angle above the horizon at `current_time`,
measured in degrees. Negative values indicate the moon is below
the horizon.
example: 15.2
moon_distance:
type: number
format: float
description: |
Distance from Earth to the moon at `current_time`, in kilometers.
example: 384400.0
moon_azimuth:
type: number
format: float
description: |
The azimuth angle of the moon at `current_time`, indicating its
compass direction in degrees.
example: 220.5
moon_parallactic_angle:
type: number
format: float
description: |
The angle between the celestial pole and the moon's position
relative to the observer's location, measured in degrees.
example: 30.1
moon_illumination_percentage:
type: string
description: |
The percentage of the moon's surface illuminated by sunlight
as viewed from Earth. Returned as a string with two decimal
places. Negative values indicate a waning phase.
example: "25.40"
moon_angle:
type: number
format: float
description: |
The moon-sun ecliptic elongation angle, normalized to the
0–360° range. This is the phase angle used to derive
`moon_phase` and `moon_illumination_percentage`; it is not
the moon's angular diameter.
example: 357.01
AstronomyTimeSeriesEntry:
type: object
description: |
Astronomical data for a single calendar day within the time series
response.
Contains event times for sunrise, sunset, moonrise, moonset,
twilight phases, solar noon, and day length.
Note: Real-time positional data (sun/moon altitude, azimuth,
distance, parallactic angle, illumination percentage, and moon
angle) is not included in time series entries.
properties:
time_zone:
type: string
description: |
The IANA timezone identifier used for timestamp conversion.
This field appears only when the `time_zone` query parameter
was provided in the request.
example: "Europe/London"
date:
type: string
description: The calendar date for this entry, in `yyyy-MM-dd` format.
example: "2026-03-18"
mid_night:
type: string
description: Astronomical midnight (nadir) for the given date.
example: "00:06"
night_end:
type: string
description: End of night / start of astronomical twilight in the morning.
example: "04:49"
morning:
$ref: "#/components/schemas/TwilightPhase"
sunrise:
type: string
description: |
Time at which the sun rises, in `HH:mm` format. Returns `"-:-"`
if the sun does not rise on this date.
example: "06:20"
sunset:
type: string
description: |
Time at which the sun sets, in `HH:mm` format. Returns `"-:-"`
if the sun does not set on this date.
example: "19:00"
evening:
$ref: "#/components/schemas/TwilightPhase"
night_begin:
type: string
description: Start of night / end of astronomical twilight in the evening.
example: "20:31"
sun_status:
type: string
description: |
Current state of the sun relative to the horizon. See
`AstronomyData.sun_status` for possible values.
example: "-"
solar_noon:
type: string
description: Time when the sun is at its highest point in the sky.
example: "12:40"
day_length:
type: string
description: |
Total daylight duration from sunrise to sunset, in `HH:mm`
format. Returns `"-:-"` if sunrise or sunset does not occur
on this date (polar day or polar night).
example: "12:40"
moon_phase:
type: string
description: The phase of the moon on this date.
enum:
- NEW_MOON
- WAXING_CRESCENT
- FIRST_QUARTER
- WAXING_GIBBOUS
- FULL_MOON
- WANING_GIBBOUS
- LAST_QUARTER
- WANING_CRESCENT
example: "WAXING_CRESCENT"
moonrise:
type: string
description: |
Time at which the moon rises, in `HH:mm` format. Returns `"-:-"`
if the moon does not rise on this date.
example: "08:45"
moonset:
type: string
description: |
Time at which the moon sets, in `HH:mm` format. Returns `"-:-"`
if the moon does not set on this date.
example: "22:10"
moon_status:
type: string
description: |
Current state of the moon relative to the horizon. See
`AstronomyData.moon_status` for possible values.
example: "-"