openapi: 3.2.0
info:
title: Apifreaks Api Hub For Developers IP Geolocation APIs API
version: 1.0.0
contact:
name: APIFreaks Support
url: https://apifreaks.com/contact
email: support@apifreaks.com
description: 'Operations tagged IP Geolocation APIs across 4 of this provider''s published API definitions: apifreaks-api-hub-for-developers-bulk-ip-lookup-openapi.json, apifreaks-api-hub-for-developers-bulk-ip-threat-intelligence-openapi.json, apifreaks-api-hub-for-developers-ip-locator-openapi.json, apifreaks-api-hub-for-developers-ip-threat-intelligence-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.apifreaks.com/v2.0
description: Bulk IP Lookup API Server
- url: https://api.apifreaks.com/v1.0
description: IP Threat Intelligence API Server
security:
- ApiKeyAuthHeader: []
- ApiKeyAuthQuery: []
tags:
- name: IP Geolocation APIs
paths:
/geolocation/lookup:
servers:
- url: https://api.apifreaks.com/v2.0
description: Bulk IP Lookup API Server
post:
tags:
- IP Geolocation APIs
summary: Retrieve geolocation and threat intelligence data for multiple IP addresses in a single request
description: Get detailed IP geolocation data for multiple IP addresses including country, city, timezone, currency, and optional threat intelligence information. Supports up to 50,000 IP addresses per request.
operationId: bulkIpLookup
parameters:
- name: format
in: query
required: false
description: Format of the response.
schema:
type: string
enum:
- json
- xml
default: json
- name: lang
in: query
required: false
description: 'Response language for location fields. Default: en.'
schema:
type: string
enum:
- en
- de
- ru
- ja
- fr
- cn
- es
- cs
- it
- ko
- fa
- pt
default: en
- name: fields
in: query
required: false
description: Comma-separated list of fields to include in the response. For example, `location` includes all location fields, `location.city` is a specific field.
schema:
type: string
- name: excludes
in: query
required: false
description: Comma-separated list of fields to exclude from response.
schema:
type: string
- name: include
in: query
required: false
description: 'Comma-separated list of additional data modules to include. Possible values: security (threat intelligence), hostname (IP-Hostname lookup), liveHostname (live hostname lookup), user_agent (parse User-Agent header), abuse (abuse contact info), * (all modules).'
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkIpLookupRequest'
examples:
typicalRequest:
summary: Typical bulk lookup request
value:
ips:
- 8.8.8.8
- 1.1.1.1
responses:
'200':
description: Successful geolocation response. Each item corresponds to one requested IP, in the same order; an IP that fails validation (invalid, bogon, reserved, or not found) yields an error item instead of a location result.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkIpLookupResponse'
examples:
typicalSuccess:
summary: Typical successful response
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
city: Mountain View
zipcode: 94043-1351
latitude: '37.42240'
longitude: '-122.08421'
is_eu: false
country_flag: https://ipgeolocation.io/static/flags/us_64.png
geoname_id: '6301403'
country_emoji: 🇺🇸
country_metadata:
calling_code: '+1'
tld: .us
languages:
- en-US
- es-US
- haw
- fr
network:
connection_type: ''
route: 8.8.8.0/24
is_anycast: true
currency:
code: USD
name: US Dollar
symbol: $
asn:
as_number: AS15169
organization: Google LLC
country: US
type: BUSINESS
domain: google.com
date_allocated: '2000-03-30'
rir: ARIN
company:
name: Google LLC
type: HOSTING
domain: google.com
time_zone:
name: America/Los_Angeles
offset: -8
offset_with_dst: -7
current_time: 2026-07-08 03:21:52.843-0700
current_time_unix: 1783506112.843
current_tz_abbreviation: PDT
current_tz_full_name: Pacific Daylight Time
standard_tz_abbreviation: PST
standard_tz_full_name: Pacific Standard Time
is_dst: true
dst_savings: 1
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
- ip: 1.1.1.1
location:
continent_code: OC
continent_name: Oceania
country_code2: AU
country_code3: AUS
country_name: Australia
country_name_official: Commonwealth of Australia
country_capital: Canberra
state_prov: Queensland
state_code: AU-QLD
district: Brisbane
city: South Brisbane
zipcode: '4101'
latitude: '-27.47301'
longitude: '153.01425'
is_eu: false
country_flag: https://ipgeolocation.io/static/flags/au_64.png
geoname_id: '10113228'
country_emoji: 🇦🇺
country_metadata:
calling_code: '+61'
tld: .au
languages:
- en-AU
network:
connection_type: ''
route: 1.1.1.0/24
is_anycast: true
currency:
code: AUD
name: Australian Dollar
symbol: A$
asn:
as_number: AS13335
organization: Cloudflare, Inc.
country: US
type: BUSINESS
domain: cloudflare.com
date_allocated: '2010-07-14'
rir: ARIN
company:
name: APNIC Research and Development
type: ''
domain: ''
time_zone:
name: Australia/Brisbane
offset: 10
offset_with_dst: 10
current_time: 2026-07-08 20:21:52.843+1000
current_time_unix: 1783506112.843
current_tz_abbreviation: AEST
current_tz_full_name: Australian Eastern Standard Time
standard_tz_abbreviation: AEST
standard_tz_full_name: Australian Eastern Standard Time
is_dst: false
dst_savings: 0
dst_exists: false
dst_tz_abbreviation: ''
dst_tz_full_name: ''
dst_start: {}
dst_end: {}
partialFailure:
summary: Response with an invalid IP mixed in — that item returns an error object instead of location data
value:
- message: Provided name, service or IP address 'not-an-ip' is not valid.
- 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
city: Mountain View
zipcode: 94043-1351
latitude: '37.42240'
longitude: '-122.08421'
is_eu: false
country_flag: https://ipgeolocation.io/static/flags/us_64.png
geoname_id: '6301403'
country_emoji: 🇺🇸
country_metadata:
calling_code: '+1'
tld: .us
languages:
- en-US
- es-US
- haw
- fr
network:
connection_type: ''
route: 8.8.8.0/24
is_anycast: true
currency:
code: USD
name: US Dollar
symbol: $
asn:
as_number: AS15169
organization: Google LLC
country: US
type: BUSINESS
domain: google.com
date_allocated: '2000-03-30'
rir: ARIN
company:
name: Google LLC
type: HOSTING
domain: google.com
time_zone:
name: America/Los_Angeles
offset: -8
offset_with_dst: -7
current_time: 2026-07-22 06:08:52.526-0700
current_time_unix: 1784725732.526
current_tz_abbreviation: PDT
current_tz_full_name: Pacific Daylight Time
standard_tz_abbreviation: PST
standard_tz_full_name: Pacific Standard Time
is_dst: true
dst_savings: 1
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
bogonOrNotFound:
summary: Bogon, reserved, or not-in-database IP — returns an error object for that item
value:
- message: '''127.0.0.1'' is a bogon IP address.'
'400':
description: Bad Request — Invalid or missing parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidRequestBody:
summary: Missing, empty, or malformed `ips` in the request body
value:
error: Invalid request body Exception
message: Please provide data in required format in request body
path: /v2.0/geolocation/lookup
status: 400
timestamp: '2026-07-22T13:08:51.422Z'
missingApiKey:
summary: No API key provided
value:
error: Invalid Param Exception
message: Please provide apiKey
path: /v2.0/geolocation/lookup
status: 400
timestamp: '2026-07-22T13:09:02.595Z'
'413':
description: Payload Too Large — Request body exceeds the maximum allowed size
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
payloadTooLarge:
summary: Request body exceeds the maximum size limit
value:
error: Payload too large Exception
message: Maximum request body size limit exceeded
path: /v2.0/geolocation/lookup
status: 413
timestamp: '2026-07-22T13:09:13.142Z'
get:
tags:
- IP Geolocation APIs
summary: Retrieve real-time and accurate IP geolocation and threat intelligence information for an IPv4 or IPv6 address
description: Get detailed IP geolocation data for an IP address including country, city, timezone, currency, and optional threat intelligence and user-agent information.
operationId: ipLookup
parameters:
- name: format
in: query
required: false
description: Format of the response.
schema:
type: string
enum:
- json
- xml
default: json
- name: ip
in: query
required: false
description: IPv4, IPv6, or hostname for geolocation lookup.
schema:
type: string
- name: lang
in: query
required: false
description: 'Response language for location fields. Default: en.'
schema:
type: string
enum:
- en
- de
- ru
- ja
- fr
- cn
- es
- cs
- it
- ko
- fa
- pt
default: en
- name: fields
in: query
required: false
description: Comma-separated list of fields to include in response. For example, `location` includes all location fields, `location.city` is a specific field.
schema:
type: string
- name: excludes
in: query
required: false
description: Comma-separated list of fields to exclude from response.
schema:
type: string
- name: include
in: query
required: false
description: 'Comma-separated list of additional data modules to include. Possible values: security (threat intelligence), hostname (IP-Hostname lookup), liveHostname (live hostname lookup), hostnameFallbackLive (hostname with live fallback), user_agent (parse User-Agent header), abuse (abuse contact info), dma_code (DMA code), geo_accuracy (accuracy_radius, confidence, locality), * (all modules).'
schema:
type: string
responses:
'200':
description: Successful geolocation response
content:
application/json:
schema:
$ref: '#/components/schemas/IpLookupResponse'
examples:
typicalSuccess:
summary: Typical successful response
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
city: Mountain View
zipcode: 94043-1351
latitude: '37.42240'
longitude: '-122.08421'
is_eu: false
country_flag: https://ipgeolocation.io/static/flags/us_64.png
geoname_id: '6301403'
country_emoji: 🇺🇸
country_metadata:
calling_code: '+1'
tld: .us
languages:
- en-US
- es-US
- haw
- fr
network:
connection_type: ''
route: 8.8.8.0/24
is_anycast: true
currency:
code: USD
name: US Dollar
symbol: $
asn:
as_number: AS15169
organization: Google LLC
country: US
type: BUSINESS
domain: google.com
date_allocated: '2000-03-30'
rir: ARIN
company:
name: Google LLC
type: HOSTING
domain: google.com
time_zone:
name: America/Los_Angeles
offset: -8
offset_with_dst: -7
current_time: 2026-07-08 03:03:31.835-0700
current_time_unix: 1783505011.835
current_tz_abbreviation: PDT
current_tz_full_name: Pacific Daylight Time
standard_tz_abbreviation: PST
standard_tz_full_name: Pacific Standard Time
is_dst: true
dst_savings: 1
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 — Invalid or missing parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
examples:
badRequest:
summary: Missing or invalid parameters
value:
message: The request was unacceptable. Typically due to missing or invalid parameters.
'404':
description: Not Found — IP address not in database
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
examples:
notFound:
summary: IP address not in database
value:
message: Provided IP address '255.255.255.255' doesn't exist in our database.
'423':
description: Locked — Bogon or reserved IP address
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse_2'
examples:
locked:
summary: Bogon or reserved IP address
value:
message: '''127.0.0.1'' is a bogon (Internet Assigned Numbers Authority) IP address.'
/ip/security:
servers:
- url: https://api.apifreaks.com/v1.0
description: IP Threat Intelligence API Server
post:
tags:
- IP Geolocation APIs
summary: Retrieve threat intelligence data for multiple IP addresses in a single request
description: Get security profiles including threat score, VPN, proxy, Tor, bot, and spam detection for up to 50,000 IPs per request. Each item in the response array corresponds to one requested IP; invalid or bogon IPs return a per-item error object.
operationId: bulkIpSecurityLookup
parameters:
- name: format
in: query
required: false
description: Format of the response.
schema:
type: string
enum:
- json
- xml
default: json
- name: fields
in: query
required: false
description: Comma-separated list of fields to return. Supports dot notation (e.g. security.threat_score).
schema:
type: string
- name: excludes
in: query
required: false
description: Comma-separated list of fields to remove from the response. Supports dot notation (e.g. security.is_tor).
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkIpSecurityRequest'
examples:
typicalRequest:
summary: Typical bulk threat intelligence request
value:
ips:
- 8.8.8.8
- 1.1.1.1
- 45.33.32.156
responses:
'200':
description: Successful threat intelligence response. The response array always contains one item for each input IP, preserving order; an IP that fails validation (invalid, bogon, reserved, or not found) yields an error item instead of a security result.
content:
application/json:
schema:
$ref: '#/components/schemas/BulkIpSecurityResponse'
examples:
typicalSuccess:
summary: Typical successful response
value:
- ip: 8.8.8.8
security:
threat_score: 5
is_tor: false
is_proxy: false
proxy_provider_names: []
proxy_confidence_score: 0
proxy_last_seen: ''
is_residential_proxy: false
is_vpn: false
vpn_provider_names: []
vpn_confidence_score: 0
vpn_last_seen: ''
is_relay: false
relay_provider_name: ''
is_anonymous: false
is_known_attacker: false
is_bot: false
is_spam: false
is_cloud_provider: true
cloud_provider_name: Google LLC
- ip: 1.1.1.1
security:
threat_score: 5
is_tor: false
is_proxy: false
proxy_provider_names: []
proxy_confidence_score: 0
proxy_last_seen: ''
is_residential_proxy: false
is_vpn: false
vpn_provider_names: []
vpn_confidence_score: 0
vpn_last_seen: ''
is_relay: false
relay_provider_name: ''
is_anonymous: false
is_known_attacker: false
is_bot: false
is_spam: false
is_cloud_provider: true
cloud_provider_name: Cloudflare, Inc.
partialFailure:
summary: Response with an invalid IP mixed in - that item returns an error object instead of security data
value:
- message: Provided IP address 'not-an-ip' is not valid
- ip: 8.8.8.8
security:
threat_score: 5
is_tor: false
is_proxy: false
proxy_provider_names: []
proxy_confidence_score: 0
proxy_last_seen: ''
is_residential_proxy: false
is_vpn: false
vpn_provider_names: []
vpn_confidence_score: 0
vpn_last_seen: ''
is_relay: false
relay_provider_name: ''
is_anonymous: false
is_known_attacker: false
is_bot: false
is_spam: false
is_cloud_provider: true
cloud_provider_name: Google LLC
bogonIp:
summary: Bogon or reserved IP - returns an error object for that item
value:
- message: '''127.0.0.1'' is a bogon IP address.'
'400':
description: Bad Request - Missing, empty, or malformed request body
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidRequestBody:
summary: Missing, empty, or malformed `ips` in the request body
value:
error: Invalid request body Exception
message: Please provide data in required format in request body
path: /v1.0/ip/security
status: 400
timestamp: '2026-07-22T14:03:26.577Z'
get:
tags:
- IP Geolocation APIs
summary: Retrieve real-time threat intelligence and security signals for an IPv4 or IPv6 address
description: Get a threat score along with VPN, proxy, Tor, relay, bot, spam, known-attacker, and cloud-provider detection flags for an IP address.
operationId: ipSecurityLookup
parameters:
- name: format
in: query
required: false
description: Format of the response.
schema:
type: string
enum:
- json
- xml
default: json
- name: ip
in: query
required: false
description: IPv4 or IPv6 address to check for threat intelligence and security signals. If omitted, the public IP of the requesting client is used.
schema:
type: string
- name: fields
in: query
required: false
description: Comma-separated list of fields to return. Supports dot notation (e.g. `security.threat_score`).
schema:
type: string
- name: excludes
in: query
required: false
description: Comma-separated list of fields to remove from the response. Supports dot notation (e.g. `security.is_tor`). The `ip` field is always included and cannot be excluded.
schema:
type: string
responses:
'200':
description: Successful threat intelligence response
content:
application/json:
schema:
$ref: '#/components/schemas/IpSecurityResponse'
examples:
typicalSuccess:
summary: Typical successful response
value:
ip: 8.8.8.8
security:
threat_score: 5
is_tor: false
is_proxy: false
proxy_provider_names: []
proxy_confidence_score: 0
proxy_last_seen: ''
is_residential_proxy: false
is_vpn: false
vpn_provider_names: []
vpn_confidence_score: 0
vpn_last_seen: ''
is_relay: false
relay_provider_name: ''
is_anonymous: false
is_known_attacker: false
is_bot: false
is_spam: false
is_cloud_provider: true
cloud_provider_name: Google LLC
'400':
description: Bad Request — Invalid or missing IP address
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidIp:
summary: Malformed IP address
value:
message: Provided IP address 'invalid' is not valid
'423':
description: Locked — Bogon or reserved IP address
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
locked:
summary: Bogon or reserved IP address
value:
message: '''10.0.0.1'' is a bogon IP address.'
components:
schemas:
Currency:
type: object
description: Currency information for the IP's country.
properties:
code:
type: string
description: Currency code (ISO 4217).
name:
type: string
description: Currency name (ISO 4217).
symbol:
type: string
description: Currency symbol.
BulkIpSecurityRequest:
type: object
required:
- ips
description: Request body for bulk IP threat intelligence lookup.
properties:
ips:
type: array
description: List of 1–50,000 IPv4 and/or IPv6 addresses to look up for threat intelligence data.
maxItems: 50000
items:
type: string
BulkIpLookupRequest:
type: object
required:
- ips
description: Request body for bulk IP geolocation lookup.
properties:
ips:
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apifreaks-api-hub-for-developers/refs/heads/main/openapi/apifreaks-api-hub-for-developers-ip-geolocation-apis-api-openapi.yml