Reference - IP Enrichment API
Reference information for the 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
Warning: Beta API
The IP Enrichment API is currently in beta and the information in this section as well as API functionality are subject to change.
Please report any issues or feedback to [email protected] and/or to your Data Consultant.
If you are an existing PDL customer and would like to discuss using the IP Enrichment API, please reach out to your Customer Success Manager or email us at [email protected].
If you’ve interested in the IP Enrichment API but are not a current PDL customer, please reach out to us for more information.
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 |
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 |
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.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] |
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": "peopledatalabs",
"website": "peopledatalabs.com",
"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"
]
}
}
}
Errors
If the request encounters an error, it will instead return an Error Response in the format described in Errors.
Updated about 1 month ago