Authentication
Getting your API key
Use your API key to authenticate requests to the IP Trust API. Your API key is available from the API Key section in the dashboard. Your API key should be supplied in the X-API-Key request header.
Endpoint
GET /ip/{ip}
Look up intelligence data for the supplied IPv4 or IPv6 address. Pass the target IP as a path parameter and your API key in the X-API-Key request header. The response is a single JSON object containing all data points available on your plan.
GET
https://api.iptrust.co/ip/{ip_address}
Example request
Request
Response codes
The API uses standard HTTP status codes. Successful lookups always return 200.
| Code | Description |
|---|---|
| 200 OK | Successful lookup. The response body contains the IP intelligence JSON object. |
| 400 | Bad request. The IP address is missing or not a valid IPv4/IPv6 address. |
| 401 | Unauthorized. The API key is missing or invalid. |
| 403 | Forbidden. Your API key does not have access to this resource. |
| 429 | Rate limited. You have exceeded your plan's request quota or rate limit. |
| 500 | Internal server error. An unexpected error occurred. Please retry or contact support. |
Response body
A successful 200 response returns a JSON object with the following fields. The fields you receive depend on your plan. Higher-tier plans include all fields from lower tiers.
| JSON Field | Description | Plans |
|---|---|---|
| { | ||
| "ip": "74.148.39.34", | The queried IP address, echoed back in the response. | Essential Plus Premium |
| "is_bogon": false, | Whether the IP belongs to a bogon (unroutable/reserved) range. | Essential Plus Premium |
| "asn": { | ||
| "number": "AS8075", | The Autonomous System Number that announces this IP prefix. | Essential Plus Premium |
| "name": "MICROSOFT-CORP-MSN-AS-BLOCK", | The registered name of the AS as listed by the RIR. | Essential Plus Premium |
| "company": "Microsoft Corporation", | The legal organisation name that owns the AS. | Essential Plus Premium |
| "country": "US", | ISO 3166-1 alpha-2 country code where the AS is registered. | Essential Plus Premium |
| "route": "74.144.0.0/12", | The most-specific BGP route prefix that contains this IP. | Essential Plus Premium |
| "rir": "ARIN", | The Regional Internet Registry responsible for this address block (e.g. ARIN, RIPE, APNIC). | Essential Plus Premium |
| "domain": "www.microsoft.com", | optional Primary domain associated with the AS owner, if available. | Essential Plus Premium |
| "type": "hosting", | optionalClassification of the AS, if available. One of: isp, hosting, business, government, education. |
Plus Premium |
| "description": "Provides consumer and enterprise software...", | optional Human-readable description of the organisation that owns this AS. | Plus Premium |
| "risk": 0.9, | optional Numeric risk score for the AS, from 0.0 (very low risk) to 1.0 (very high risk), based on observed threat signals from Friendly Captcha. Only provided when Friendly Captcha has observed enough traffic to make a determination. | Premium |
| "risk_label": "very_high", | optional Human-readable risk level: very_low, low, moderate, high, or very_high. |
Premium |
| "risk_types": ["request_frequency", "repeated_abuse"] | optional List of risk signal categories that contributed to the risk score, if available:
|
Premium |
| }, | ||
| "location": { | ||
| "resolution": "city", | Precision of the location data for this IP. One of: city, state, country. A country resolution means the city and state fields may be empty. |
Essential Plus Premium |
| "city": "Barcelona", | City-level location of the IP address. | Essential Plus Premium |
| "state": "Barcelona", | State, province, or top-level administrative region. | Essential Plus Premium |
| "country": "Spain", | Full country name derived from the IP's geolocation data. | Essential Plus Premium |
| "latitude": 41.389, | Approximate latitude coordinate of the IP's location (WGS84). | Essential Plus Premium |
| "longitude": 2.159, | Approximate longitude coordinate of the IP's location (WGS84). | Essential Plus Premium |
| "meta": { | ||
| "country_iso2": "ES", | ISO 3166-1 alpha-2 code. | Essential Plus Premium |
| "country_iso3": "ESP", | ISO 3166-1 alpha-3 country code. | Essential Plus Premium |
| "country_numeric_code": "724", | ISO 3166-1 numeric country code. | Essential Plus Premium |
| "country_phone_code": "34", | International dialling code for the country. | Essential Plus Premium |
| "country_capital": "Madrid", | Capital city of the country. | Essential Plus Premium |
| "country_currency": "EUR", | ISO 4217 currency code used in the country. | Essential Plus Premium |
| "country_currency_name": "Euro", | Full name of the country's currency. | Essential Plus Premium |
| "country_native": "España", | Country name in the local/native language. | Essential Plus Premium |
| "country_region": "Europe", | UN geographic macro-region (e.g. Europe, Asia, Americas). | Essential Plus Premium |
| "country_subregion": "Southern Europe", | UN geographic sub-region (e.g. Western Europe, South-Eastern Asia). | Essential Plus Premium |
| "country_emoji": "🇪🇸", | Country flag as a Unicode emoji character. | Essential Plus Premium |
| "country_emoji_u": "U+1F1EA U+1F1F8" | Country flag emoji as Unicode code points. | Essential Plus Premium |
| } | ||
| }, | ||
| "company": { | ||
| "name": "mawa-solutions GmbH", | The legal name of the company or organisation operating at this IP address. | Plus Premium |
| "type": "business", | optional Organisation classification: isp, business, hosting, government, education. |
Plus Premium |
| "domain": "www.mawa-solutions.com", | optional Primary website domain of the company. | Plus Premium |
| "description": "Provides SAP-based time-tracking..." | optional Brief description of the company's products or services. | Plus Premium |
| }, | ||
| "known_bot": { | ||
| "detected": true, | Whether a known bot or crawler was detected for this IP. | Plus Premium |
| "bot_type": "ai", | optional Category of bot: crawler, ai, or other. |
Plus Premium |
| "name": "chatgpt_user" | optional Identifier of the specific bot. Possible values:
|
Plus Premium |
| }, | ||
| "hosting": { | ||
| "detected": true, | Whether the IP belongs to a known hosting or cloud infrastructure provider. | Plus Premium |
| "domain": "www.microsoft.com", | optional Website domain of the hosting provider. | Plus Premium |
| "name": "Microsoft Limited" | optional Name of the hosting or cloud provider operating at this IP. | Plus Premium |
| }, | ||
| "abuse_contact": { | ||
| "address": "One Microsoft Way, Redmond, WA 98052", | optional Physical mailing address for the abuse contact of the network owner. | Premium |
| "email": "abuse@microsoft.com", | optional Email address for reporting abuse originating from this network. | Premium |
| "name": "Microsoft Abuse Contact" | optional Name of the person or team responsible for abuse reports. | Premium |
| }, | ||
| "tor_exit_node": { | ||
| "detected": true | Whether this IP is a known Tor network exit node. | Premium |
| }, | ||
| "privacy_relay": { | ||
| "detected": true, | Whether the IP is part of a commercial privacy relay service. | Premium |
| "provider": "icloud_private_relay" | optional The privacy relay provider identifier. For now, always icloud_private_relay. |
|
| "proxy": { | ||
| "detected": true, | Whether this IP has been detected as an active proxy server. | Premium |
| "type": "residential", | optional Type of proxy, one of:
|
Premium |
| "last_detected": "2025-11-15" | optional Date (ISO 8601) when proxy activity was last observed for this IP, if available. | Premium |
| }, | ||
| "vpn": { | ||
| "detected": true, | Whether this IP has been identified as part of a VPN service. | Premium |
| "provider": "nord_vpn", | optional Identifier of the VPN provider, if known. | Premium |
| "last_detected": "2025-11-15" | optional Date (ISO 8601) when VPN activity was last observed for this IP. | Premium |
| } | ||
| } |
Endpoint
GET /database
List the databases available for download, along with the formats and file sizes on offer and when each was last updated. Every database is listed, whether or not it is included in your plan — the entitled field tells you which ones you can download. Pass your API key in the X-API-Key request header.
GET
https://api.iptrust.co/database
Example request
Request
curl -s -H "X-API-Key: YOUR_API_KEY" \
"https://api.iptrust.co/database" | jq .
Example response
Response
{
"databases": [
{
"type": "geolocation",
"entitled": true,
"updated_at": "2026-08-24T03:12:44Z",
"formats": [
{
"format": "mmdb",
"size_bytes": 91234567,
"updated_at": "2026-08-24T03:12:44Z"
},
{
"format": "csv",
"size_bytes": 41234567,
"updated_at": "2026-08-24T03:12:44Z"
}
]
},
{
"type": "anonymization",
"entitled": false,
"updated_at": "2026-08-24T03:14:02Z",
"formats": [ ... ]
}
]
}
Response fields
| Field | Description |
|---|---|
| type | Identifier of the database: asn, company, geolocation, abusecontact, knownbots, hosting or anonymization. Use this value as the type when requesting a download. |
| entitled | Whether your plan includes downloads of this database. Requesting a download for a database where this is false returns 403. |
| updated_at | When the most recently refreshed file for this database was published (ISO 8601, UTC). |
| formats | The formats this database is published in. mmdb is a MaxMind DB file, readable by any standard MMDB library; csv is a gzipped CSV export. |
| size_bytes | Size of the file in bytes, as published. For csv this is the compressed size. |
Response codes
| Code | Description |
|---|---|
| 200 OK | The response body contains the list of available databases. |
| 401 | Unauthorized. The API key is missing or invalid. |
| 500 | Internal server error. An unexpected error occurred. Please retry or contact support. |
Endpoint
POST /database/download
Generate a temporary download link for a single database file. The endpoint returns a signed URL that you then fetch directly — no API key is needed on the download itself, so it can be handed straight to curl, wget or your download tooling. Send the database and format as a JSON body, with your API key in the X-API-Key request header.
POST
https://api.iptrust.co/database/download
Request body
| Field | Description |
|---|---|
| type | Required. The database to download, as returned by GET /database — for example geolocation. |
| format | Required. Either mmdb or csv. |
Example request
Request
curl -s -X POST \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "geolocation", "format": "mmdb"}' \
"https://api.iptrust.co/database/download" | jq .
Example response
Response
{
"type": "geolocation",
"format": "mmdb",
"filename": "iptrust-geolocation.mmdb",
"url": "https://files.iptrust.co/latest/iptrust-geolocation.mmdb?X-Amz-Algorithm=...",
"size_bytes": 91234567,
"updated_at": "2026-08-24T03:12:44Z",
"expires_at": "2026-08-24T11:41:09Z"
}
Fetch the file by following the url directly:
Download
curl -L -o iptrust-geolocation.mmdb "<url from the response>"
Link lifetime
Download links are valid for one hour from the moment they are issued, shown in the expires_at field. Requesting the same database and format again within roughly half that window returns the link that is already in flight rather than minting a new one, so treat expires_at as authoritative and start your download promptly. Anyone holding the link can download the file until it expires, so treat it as a credential. Once it expires, request a new one.
Databases are refreshed regularly, so the url always resolves to the newest published file for that database and format. Downloads do not count towards your monthly API request quota.
Response codes
| Code | Description |
|---|---|
| 200 OK | The response body contains the signed download URL. |
| 400 | Bad request. The body is malformed, or type or format is missing or not a recognised value. |
| 401 | Unauthorized. The API key is missing or invalid. |
| 403 | Forbidden. Your plan does not include downloads of this database. |
| 404 | Not found. The requested database is not currently published in that format. |
| 500 | Internal server error. An unexpected error occurred. Please retry or contact support. |
LLM-Friendly Docs
Plain-text API reference
Need to feed our docs to an AI coding assistant or LLM? We publish a plain-text Markdown version of this documentation at /docs/llms.txt, optimised for machine consumption.