IP Address Geolocation with Confidence Area and Hazard Report API

This API combines everything in the IP Address Geolocation with Confidence Area API with the Hazard Report — a set of risk signals designed to help you make faster, more informed decisions about incoming traffic.

Most risk tools only look backwards: is this IP on a blocklist? Has it been flagged before? The Hazard Report adds a forward-looking dimension. It assesses whether an IP belongs to hosting infrastructure rather than a residential network — a strong indicator of automated or non-human traffic — even when there's no prior incident history. That combination of reactive signals and proactive indicators gives you a more complete picture of threat likelihood than blocklist checks alone.

For a detailed breakdown of what the Hazard Report contains and how to interpret it, see Understanding the Hazard Report.

GEThttps://api-bdc.net/data/ip-geolocation-full

Parameters

ParameterTypeRequiredDescription
ipstringOptionalIPv4 IP address in a string or numeric format or IPv6 IP address in a string format. If omitted, the caller’s IP address is assumed
localityLanguagestringOptionalPreferred language for locality names in ISO 639-1 format, such as 'en' for English, 'es' for Spanish etc. If the requested language is unavailable for a requested location, it will default to English. If no English variant is available, will provide the native, local names. Use 'default' as the requested value to automatically adjust the language to the first administrative language in the Country.
keystringOptionalYour API key

Responses

200OK

Sample Request

https://api-bdc.net/data/ip-geolocation-full?ip=18.209.237.103&localityLanguage=en&key=[YOUR API KEY]

Sample Response

JSON View

Response Schema

ipstringThe requested IP address in string format (IPv4 or IPv6).
localityLanguageRequestedstringThe locality language that was used for this response, as requested via the `localityLanguage` parameter (ISO 639-1 code, e.g. "en").
isReachableGloballybooleanIndicates whether the IP address is present on the global BGP routing table and therefore reachable from the public Internet. If `false`, the address is not in active use and cannot be geolocated.
▶countryobjectcountry object
isoAlpha2stringISO 3166-1 Alpha-2 code
isoAlpha3stringISO 3166-1 Alpha-3 code
m49CodeintegerUnited Nations M.49 code
namestringCountry name localised to the language as defined by 'localityLanguage' request parameter
isoNamestringThe short English country name as defined by ISO 3166-1 (e.g. "Australia").
isoNameFullstringThe full official English country name as defined by ISO 3166-1 (e.g. "Commonwealth of Australia").
▶isoAdminLanguagesarrayAdministrative languages as defined by ISO 3166-1 standard
isoAlpha3stringISO 3166-1 Alpha-3 code
isoAlpha2stringISO 3166-1 Alpha-2 code
isoNamestringISO 3166-1 Language name
nativeNamestringA native name
unRegionstringRegion name as defined by the United Nations
▶currencyobjectcurrency object
numericCodeintegerISO 4217 standard numeric code
codestringISO 4217 standard code
namestringISO 4217 English name
minorUnitsintegerISO 4217 minor units as the currency exponent (e.g. 2 = 1/100)
▶wbRegionobjectwbRegion object
idstringworld bank identification number. the expected values are: 'LCN','NA','SAS','SSF','ECS','MEA','EAS','NAC'
iso2Codestringiso 2 letters code. the expected values are: 'ZJ','NA','8S','ZG','Z7','ZQ','Z4','XU'
valuestringregion name. the expected values are: 'Latin America & Caribbean','Aggregates','South Asia', 'Sub-Saharan Africa','Europe & Central Asia','Middle East & North Africa','East Asia & Pacific','North America'
▶wbIncomeLevelobjectwbIncomeLevel object
idstringworld bank identification number. the expected values are: 'HIC','NA','LIC','LMC','UMC','INX'
iso2Codestringiso 2 letters code. the expected values are: 'XD','NA','XM','XN','XT','XY'
valuestringincome level name. the expected values are: 'High income','Aggregates','Low income','Lower middle income','Upper middle income','Not classified'
callingCodestringThe international dialling (calling) code for the country, without the leading "+" (e.g. "1" for the US, "61" for Australia).
countryFlagEmojistringThe country flag as a Unicode emoji (e.g. "🇦🇺" for Australia), composed from the ISO 3166-1 Alpha-2 regional indicator symbols.
wikidataIdstringWikidata item identifier, if available
geonameIdintegerA unique identifier as is given by GeoNames.org
isIndependentbooleanDetermines if the country/territory is independent according to ISO 3166 records
▶locationobjectlocation object
principalSubdivisionstringLocalised principal subdivision name in the requested language, if available
isoPrincipalSubdivisionstringPrincipal subdivision name as defined by ISO 3166-2 standard
isoPrincipalSubdivisionCodestringPrincipal subdivision code as defined by ISO 3166-2 standard
continentstringLocalised Continent name in the requested language, if available
continentCodestringThe ISO continent code for the location (e.g. "EU" for Europe, "AS" for Asia, "OC" for Oceania)
citystringThe most significant populated place this location belongs. It will likely be the City name in the language requested. If unavailable, use the locality name field as a failover
localityNamestringRepresents the smallest geographic area recognised to which the target belongs. The language, if available, is as defined by the 'localityLanguage' request parameter
postcodestringPostcode, if available
latitudenumberThe latitude of the estimated geolocation point in decimal degrees (WGS 84).
longitudenumberThe longitude of the estimated geolocation point in decimal degrees (WGS 84).
plusCodestringThe Open Location Code (Plus Code) for this location (e.g. "4RRH46J6+22"). A compact, address-independent encoding of coordinates.
▶fipsobjectFIPS code object, omitted if unavailable. FIPS (Federal Information Processing Standards) Codes are codes used by the Census Bureau to uniquely identify places in the US. Visit FIPS FAQ page for more information.
statestringState-level FIPS codes have two digits
countystringA three digits County-level FIPS code.
countySubdivisionstringFIPS five digits County Subdivision Code
placestringFIPS five digits place code, omitted if unavailable
csdCodestringCSD (Census Subdivision) code, omitted if unavailable. Canadian Geographic Codes. Visit CSD FAQ page for more information.
▶timeZoneobjecttimeZone object
ianaTimeIdstringThe unique identifier of the time zone from the IANA Time Zone Database (e.g., "America/New_York").
displayNamestringThe user-friendly display name for the time zone (e.g., "(UTC-05:00) Eastern Time (US & Canada)").
effectiveTimeZoneFullstringThe full name of the effective time zone, adjusted for daylight saving (e.g., "Eastern Daylight Time").
effectiveTimeZoneShortstringThe abbreviated name of the effective time zone, adjusted for daylight saving (e.g., "EDT").
utcOffsetSecondsintegerThe effective offset from UTC in seconds, adjusted for daylight saving time.
utcOffsetstringThe effective offset from UTC, formatted as a string and adjusted for daylight saving time.
isDaylightSavingTimebooleanA boolean value indicating whether daylight saving time is currently in effect.
localTimestringThe current local time in the specified time zone, formatted in ISO 8601 "O" format.
utcTimestringThe corresponding UTC time, formatted in ISO 8601 "O" format. This value is omitted if the 'utcReference' parameter was not supplied or was invalid.
▶localityInfoobjectlocalityInfo object
▶administrativearrayAdministrative authorities as ordered by area (most significant first). Omitted if no administrative boundaries are available
namestringLocalised name of the place in the requested language, if available. The language is as defined by the 'localityLanguage' request parameter
descriptionstringLocalised description of the place in the requested language, if available. The language is as defined by the 'localityLanguage' request parameter
isoNamestringISO 3166-2 standard name, if available
orderintegerOrder value consistent across all entities in the Locality Info parent object. Ordered by geographic area (most significant first)
adminLevelintegerAn administrative level as defined by OpenStreetMaps project
isoCodestringISO 3166-2 standard code, if available
wikidataIdstringWikidata item identifier, if available
geonameIdintegerUnique identifier given by GeoNames.org, if available
chinaAdminCodestringChina Administrative division code. Only available for locations based in China and omitted for others
▶informativearrayNon-administrative boundaries as ordered by area (most significant first). Omitted if unavailable
namestringLocalised name of the place in the requested language, if available. The language is as defined by the 'localityLanguage' request parameter
descriptionstringLocalised description of the place in the requested language, if available. The language is as defined by the 'localityLanguage' request parameter
isoNamestringISO 3166-2 standard name, if available
orderintegerOrder value consistent across all entities in the Locality Info parent object. Ordered by geographic area (most significant first)
adminLevelintegerAn administrative level as defined by OpenStreetMaps project
isoCodestringISO 3166-2 standard code, if available
wikidataIdstringWikidata item identifier, if available
geonameIdintegerUnique identifier given by GeoNames.org, if available
chinaAdminCodestringChina Administrative division code. Only available for locations based in China and omitted for others
lastUpdatedstringThe UTC timestamp (ISO 8601) of when the geolocation data for this IP address was last assessed and updated.
▶networkobjectnetwork object
registrystringThe Regional Internet Registry (RIR) that administers the network block (e.g. ARIN, RIPE, APNIC, LACNIC, AFRINIC, IANA).
registryStatusstringThe registration status of the network block as recorded by the RIR (e.g. "assigned", "allocated", "reserved").
registeredCountrystringRegistered Country ISO 3166-1 Alpha-2 code
registeredCountryNamestringRegistered Country name localised to the language is as defined by 'localityLanguage' request parameter
organisationstringThe organisation or entity the network block is registered for, as recorded in the RIR database.
isReachableGloballybooleanIndicates whether the network was announced on BGP and reachable globally or not
isBogonbooleanIndicates whether the IP address is excluded from public Internet use by the authorities but announced into the global routing table via BGP
bgpPrefixstringThe BGP prefix detected on the global network, announcing the network
bgpPrefixNetworkAddressstringThe first (network) address of the BGP prefix range.
bgpPrefixLastAddressstringThe last (broadcast) address of the BGP prefix range.
totalAddressesintegerNumber of IP addresses in the Network. For IPv6 networks, the value can range up to a 128-bit unsigned integer
▶carriersarrayList of Autonomous Systems (AS) announcing this network on BGP
asnstringThe Autonomous System Number in prefixed string format (e.g. "AS13335").
asnNumericintegerThe Autonomous System Number as an unsigned integer (e.g. 13335).
organisationstringThe organisation or entity the AS is registered for, as recorded in the RIR database.
namestringThe short handle or network name assigned to the AS by the RIR (e.g. "CLOUDFLARENET").
registrystringThe Regional Internet Registry (RIR) the AS is registered with
registeredCountrystringRegistered Country ISO 3166-1 Alpha-2 code
registeredCountryNamestringRegistered Country localised name. The language is as defined by the 'localityLanguage' request parameter
registrationDatestringRegistration date in 'yyyy-mm-dd' format
registrationLastChangestringRegistration modification date in 'yyyy-mm-dd' format
totalIpv4AddressesintegerTotal number of IP addresses announced by the AS
totalIpv4PrefixesintegerTotal number of ipV4 BGP prefixes announced by the AS
totalIpv4BogonPrefixesintegerTotal number of ipV4 bogon prefixes announced by the AS
totalIpv6PrefixesintegerTotal number of ipV6 BGP prefixes announced by the AS
totalIpv6BogonPrefixesintegerTotal number of ipV6 bogon prefixes announced by the AS
rankintegerGlobal rank by total number of IP addresses announced
rankTextstringHuman-readable global rank string including the total number of ranked ASNs (e.g. "#297 out of 79,835").
▶viaCarriersarrayList of Autonomous Systems (AS) detected at the last BGP hop before the network carriers. Capped to the 5 most significant upstream peers.
asnstringThe Autonomous System Number in prefixed string format (e.g. "AS13335").
asnNumericintegerThe Autonomous System Number as an unsigned integer (e.g. 13335).
organisationstringThe organisation or entity the AS is registered for, as recorded in the RIR database.
namestringThe short handle or network name assigned to the AS by the RIR (e.g. "CLOUDFLARENET").
registrystringThe Regional Internet Registry (RIR) the AS is registered with
registeredCountrystringRegistered Country ISO 3166-1 Alpha-2 code
registeredCountryNamestringRegistered Country localised name. The language is as defined by the 'localityLanguage' request parameter
totalIpv4AddressesintegerTotal number of IP addresses announced by the AS
rankintegerGlobal rank by total number of IP addresses announced
rankTextstringHuman-readable global rank string including the total number of ranked ASNs (e.g. "#297 out of 79,835").
confidencestringThe confidence level of the geolocation estimate. Possible values: `"low"`, `"moderate"`, or `"high"`. Higher confidence indicates a smaller, more precise confidence area.
▶confidenceAreaarrayA closed polygon (list of latitude/longitude points) representing the maximum possible service area where this IP address could be located. Based on ISP historical allocation patterns and network topology. Use this to display an uncertainty region on a map.
latitudenumberLatitude in EPSG:4326 projection, as used in GPS
longitudenumberLongitude in EPSG:4326 projection, as used in GPS
securityThreatstringA human-readable summary of the most significant security threat detected for this IP address (e.g. "known as a TOR server", "known as a VPN server", "blacklisted at BLOCKLIST.de"). Returns `"unknown"` when no specific threat is identified.
▶hazardReportobjecthazardReport object
isKnownAsTorServerbooleanDetermines whether the requested ip address is known as utilised by a TOR server
isKnownAsVpnbooleanDetermines whether the requested ip address is known as utilised by a VPN server
isKnownAsProxybooleanDetermines whether the requested ip address is known as utilised by a proxy server
isSpamhausDropbooleanDetermines whether the requested ip address is listed on the Spamhaus drop all traffic list. The Spamhaus drop (don't route or peer) lists are advisory 'drop all traffic' lists, consisting of netblocks that are 'hijacked' or leased by professional spam or cyber-crime operations (used for dissemination of malware, trojan downloaders, botnet controllers)
isSpamhausEdropbooleanDetermines whether the requested ip address is listed on the Spamhaus edrop list According to Spamhaus, edrop is an extension of the drop list that includes sub-allocated netblocks controlled by spammers or cyber criminals
isSpamhausAsnDropbooleanDetermines whether the requested IP address is listed on the Spamhaus ASN-drop list. According to Spamhaus, asn-drop contains a list of autonomous system numbers controlled by spammers or cyber criminals, as well as hijacked asns
isBlacklistedUceprotectbooleanDetermines whether the requested ip address is blacklisted at uceprotect.net or backscatterer.org
isBlacklistedBlocklistDebooleanDetermines whether the requested ip address is blacklisted at blocklist.de
isKnownAsMailServerbooleanDetermines whether the requested ip address is known as utilised by an SMTP mail server
mailServerDomainstringThe last detected SMTP domain name making use of this ip address
isKnownAsPublicRouterbooleanDetermines whether the requested ip address is known as utilised by a public router
isBogonbooleanIndicates whether the IP address is excluded from public Internet use by the authorities but announced into the global routing table via BGP
isUnreachablebooleanDetermines whether the requested ip address is not reachable via the public Internet
hostingLikelihoodintegerThe likelihood (0–10) that this IP address originates from a hosting, data centre, or cloud environment. A value of 0 indicates no hosting signals detected; 10 indicates very high confidence of hosting origin.
isHostingAsnbooleanDetermines whether the requested ip address was announced by an autonomous system which is likely to publish hosting networks
isCellularbooleanDetermines whether the requested ip address was detected as utilised within a cellular network
iCloudPrivateRelaybooleanDetermines whether the requested ip address was detected as Apple iCloud Private Relay address
403Access denied, or your quota limit has exceeded

Sample Response

JSON View
404Found no valid entry for the request

Sample Response

JSON View
405The requested IP address is not valid

Sample Response

JSON View
500An error has occurred and did not complete your request. Please try again

Sample Response

JSON View