Reference - IP Enrichment API
The IP Enrichment API provides a one-to-one IP match, retrieving up-to-date information on a unique IP.
Endpoint
The endpoint for the IP Enrichment API is https://api.peopledatalabs.com/v5/ip/enrich.
IP Enrichment API Access and Billing
When the IP Enrichment API finds a matching IP address, it returns the IP record along with an HTTP response code of 200. When it doesn't find a matching IP, it returns an HTTP response code of 404. We charge per match.
Requests
See Authentication and Requests sections to see all possible ways to input a request. We recommend using a JSON object to capture input parameters and will do so in the examples.
Rate Limiting
Our default limit for free customers is 100 per minute. Our default limit for paying customers is 1,000 per minute.
Input Parameters
For more details, see Input Parameters - IP Enrichment API
You can also click on the individual parameter names in the table below to view more information on them.
| Parameter Name | Description | Example |
|---|---|---|
ip | The IP address to enrich in IPv4 or IPv6 format. | 72.212.42.169 |
api_key | Your secret API key. Note: You can also provide this in the request header instead, as shown on the Authentication page. |
Additional Input Parameters
You are not required to use the following additional input parameters. They generally transform or control various aspects of the enrichment process (returning matches or formatting results).
| Parameter Name | Description | Example |
|---|---|---|
return_ip_location | IP responses will not include location data for the IP by default. Setting return_ip_location to true will return IP specific location info. | false |
return_ip_metadata | IP responses will not include metadata for the IP by default. Setting return_ip_metadata to true will return IP specific metadata. | false |
return_if_unmatched | Setting return_if_unmatched to true will return IP specific metadata or location regardless of a company match. | false |
return_person | Setting return_person to true will return IP specific person fields. | false |
min_confidence | Return a result only if it meets the minimum confidence threshold. | high |
pretty | Whether the output should have human-readable indentation. | false |
titlecase | All text in the API responses returns as lowercase by default. Setting titlecase to true will titlecase the data in 200 responses. | false |
updated_title_roles | Set to true to return the updated taxonomy for job_title_role and job_title_subrole along with the new job_title_class field.Temporary parameter available from Oct 2024 - Feb 2024. | true |
Output Response
We return in the API response the ip record along with a 200 HTTP response code. If we do not find a match, we return a 404 HTTP response code.
Response Fields
For more details, see Output Response - IP Enrichment API
You can also click the field names in the table below to view more information on them.
| Field | Description | Type |
|---|---|---|
status | The response code. See a description of our error codes. | Integer |
data | The information about the IP address from the ip input parameter. Any fields that do not contain data will have a null value. | Object |
data.ip | Information related to the IP address. | Object |
data.ip.address | The matched IP address. | String |
data.ip.metadata | Premium fields targeted towards identifying IPs as mobile or using hosting, proxy, tor, vpn, relay or other services. Also includes domain associated with ASN block if it exists. | Object |
data.ip.location | The location associated with the IP address. | Object |
data.company | Information related to the company associated with the IP address. | Object |
data.company.confidence | How confident we are that the returned company is associated with requested IP. Will be one of the following options: very high, high, moderate, low, very low. | Enum (String) |
data.company.id | The PDL ID of the company associated with the IP address. | String |
data.company.website | The primary website of the company associated with the IP address. | String |
data.company.name | The name of the company associated with the IP address. | String |
data.company.display_name | The display name of the company associated with the IP address. | String |
data.company.location | The location of the company's primary HQ associated with the IP address. | Object |
data.company.size | The self-reported size range of the company associated with the IP address. | Enum (String) |
data.company.industry | The self-reported industry of the company associated with the IP address. | Enum (String) |
data.company.inferred_revenue | The estimated annual revenue (in USD) of the company associated with the IP address. | Enum (String) |
data.company.employee_count | The current number of employees working at the company associated with the IP address. | Integer (> 0) |
data.company.tags | Tags associated with the company associated with the IP address. | Array [String] |
data.person.confidence | How confident we are that the returned person is associated with requested IP. Will be one of the following options: very high, high, moderate, low, very low. | Enum (String) |
data.person.job_title_sub_role | The derived subrole of the person's current job title. | Enum (String) |
data.person.job_title_role | The derived role of the person's current job title. | Enum (String) |
data.person.job_title_levels | The derived level(s) of the person's current job title | Array [String] |
data.dataset_version | The release number for the current build | String |
Full Example Response
The response from the IP Enrichment API will be in this format:
{
"status": 200,
"data": {
"ip": {
"address": "72.212.42.169",
"metadata": {
"version": 4,
"mobile": false,
"hosting": false,
"proxy": false,
"tor": false,
"vpn": false,
"relay": false,
"service": null,
"asn_domain": null,
},
"location": {
"name": "phoenix, arizona, united states",
"locality": "phoenix",
"region": "arizona",
"metro": "phoenix, arizona",
"country": "united states",
"continent": "north america",
"postal_code": "85001",
"geo": "33.44838,-112.07404",
"timezone": "america/phoenix"
}
},
"company": {
"confidence": "very high",
"id": "tnHcNHbCv8MKeLh92946LAkX6PKg",
"website": "peopledatalabs.com",
"name": "people data labs",
"display_name": "People Data Labs",
"location": {
"name": "san francisco, california, united states",
"locality": "san francisco",
"region": "california",
"metro": "san francisco, california",
"country": "united states",
"continent": "north america",
"street_address": "455 market street",
"address_line_2": "suite 1670",
"postal_code": "94105",
"geo": "37.77,-122.41"
},
"size": "11-50",
"industry": "computer software",
"inferred_revenue": "$25m-$50m",
"employee_count": 129,
"tags": [
"artificial intelligence",
"data and analytics",
"machine learning",
"analytics",
"database",
"software",
"developer apis",
"data",
"people data",
"data science"
]
},
"person": {
"confidence": "very high",
"job_title_sub_role": "product",
"job_title_role": "operations",
"job_title_levels": [
"cxo"
]
},
"dataset_version": "1.1.0.2024w19"
}
}
Errors
If the request encounters an error, it will instead return an Error Response in the format described in Errors.
In general, the error codes are ubiquitous across products with one exception. The IP Enrichment API will return a 400 in situations where the IP address is known to be a Hosting Provider, Proxy, Tor, Relay, or Service. These IP addresses cannot be resolved to a specific company.
{
"status": 400,
"error": "Cannot Enrich IP",
"message": "IP is a Hosting Provider, Proxy, Tor, Relay, or Service",
"data": {
"ip": {
"address": "54.81.251.238"
}
}
}
Updated 25 days ago