DocumentationAPI Explorer ToolAPI DashboardAPI StatusRoadmapSupport
Documentation
Start Building

Examples - IP Enrichment API

Suggest Edits

Examples

When specifying query parameters within a URL, you should separate them with an ampersand (&). When specifying query parameters within a JSON object, you should use lists for the request parameters.

We've provided code samples in cURL, Python, Ruby, Go and JavaScript. If you aren't comfortable working in any of these languages, feel free to use this handy tool to convert code from cURL to the language of your choice.

💡

We want your feedback!

Do you see a bug? Is there an example you'd like to see that's not listed here?

Head over to the public roadmap and submit a bug ticket or a feature request and receive automatic notifications as your bug is resolved or your request is implemented.

Basic Usage

"I want to learn more about the data associated with an IP address."

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying your API key
CLIENT = PDLPY(
    api_key="YOUR API KEY",
)

# Create a parameters JSON object
PARAMS = {
    "ip": "72.212.42.169"
}

# Pass the parameters object to the IP Enrichment API
json_response = CLIENT.ip(**PARAMS).json()

# Check for successful response
if json_response["status"] == 200:
  record = json_response['data']

  # Print selected fields
  print(
    record['ip']["location"]["metro"],
    record['company']["name"]
  )

  print(f"Successfully enriched ip with PDL data.")

  # Save enrichment data to JSON file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

curl -X GET -G \
  'https://api.peopledatalabs.com/v5/ip/enrich'\
  -H 'X-Api-Key: xxxx' \
 	--data-urlencode 'ip=72.212.42.169'

// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

import fs from 'fs';

// Create a client, specifying your API key
const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

// Create a parameters JSON object
const params = {
  ip: "72.212.42.169"
}

// Pass the parameters object to the IP Enrichment API
PDLJSClient.ip(params).then((data) => {
    var record = data.data
    
    // Print selected fields
    console.log(
        record["ip"]["location"]["metro"],
      	record["company"]["name"]
        )
        
    console.log("Successfully enriched ip with PDL data.")
    
    // Save enrichment data to JSON file
    fs.writeFile("my_pdl_enrichment.jsonl", Buffer.from(JSON.stringify(record)), (err) => {
        if (err) throw err;
    });
}).catch((error) => {
    console.log("Enrichment unsuccessful. See error and try again.")
    console.log(error);
});

require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

# Set your API key
Peopledatalabs.api_key = 'YOUR API KEY'

# Create a parameters JSON object
PARAMS = {
    "profile": "72.212.42.169"
}

# Pass the parameters object to the IP Enrichment API
json_response = Peopledatalabs::Enrichment.ip(params: PARAMS)

# Check for successful response
if json_response['status'] == 200
    record = json_response['data']
    
    # Print selected fields
    puts \
        "#{record['ip']['location']['metro']} \
         #{record['company']['name']}"
    
    puts "Successfully enriched ip with PDL data."
    
    # Save enrichment data to JSON file
    File.open("my_pdl_enrichment.jsonl", "w") do |out|
        out.write(JSON.dump(record) + "\n")
    end
else
    puts "Enrichment unsuccessful. See error and try again."
    puts "error: #{json_response}"
end

package main

import (
    "fmt"
    "os"
    "encoding/json"
    "context"
)

// See https://github.com/peopledatalabs/peopledatalabs-go
import (
    pdl "github.com/peopledatalabs/peopledatalabs-go"
    pdlmodel "github.com/peopledatalabs/peopledatalabs-go/model"
)

func main() {
    // Set your API key
    apiKey := "YOUR API KEY"
    // Set API key as environmental variable
    // apiKey := os.Getenv("API_KEY")

    // Create a client, specifying your API key
    client := pdl.New(apiKey)
    
    // Create a parameters JSON object
    params := pdlmodel.IPParams {
        IPBaseParams: pdlmodel.IPBaseParams {
            IP: "72.212.42.169",
        }
    }

    // Pass the parameters object to the IP Enrichment API
    response, err := client.IP(context.Background(), params)
    
    // Check for successful response
    if err == nil {
        // Convert the API response to JSON
        jsonResponse, jsonErr := json.Marshal(response.Data)
        if jsonErr == nil {
            var record map[string]interface{}
            json.Unmarshal(jsonResponse, &record)
            // Print selected fields
            fmt.Println(
                       record["ip"]["location"]["metro"], 
                       record["company"]["name"])
        
            fmt.Println("Successfully enriched ip with PDL data.")
        
            // Save enrichment data to JSON file
            out, outErr := os.Create("my_pdl_enrichment.jsonl")
            defer out.Close()
            if outErr == nil {
                out.WriteString(string(jsonResponse) + "\n")
            }
            out.Sync()
        }
   	} else {
        fmt.Println("Enrichment unsuccessful. See error and try again.")
        fmt.Println("error:", err)
    }
}

import requests, json

# Set your API key
API_KEY = "YOUR API KEY"

# Set the IP Enrichment API URL
PDL_URL = "https://api.peopledatalabs.com/v5/ip/enrich"

# Create a parameters JSON object
PARAMS = {
    "api_key": API_KEY,
    "ip": "72.212.42.169"
}

# Pass the parameters object to the IP Enrichment API
json_response = requests.get(PDL_URL, params=PARAMS).json()

# Check for successful response
if json_response["status"] == 200:
  record = json_response['data']

  # Print selected fields
  print(
    record['ip']['location']['metro'],
    record['company']['name']
  )

  print(f"Successfully enriched ip with PDL data.")

  # Save enrichment data to JSON file
  with open("my_pdl_enrichment.jsonl", "w") as out:
    out.write(json.dumps(record) + "\n")
else:
  print("Enrichment unsuccessful. See error and try again.")
  print("error:", json_response)

Return the Company Associated with the IP Address

"I want to resolve/enrich the company associated with an IP address."

# Enriching an IP then resolving/enriching the IP's company
import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying your API key
CLIENT = PDLPY(
    api_key="YOUR API KEY",
)

# Create a parameters JSON object
IP_PARAMS = {"ip": "72.212.42.169"}

# Pass the parameters object to the IP Enrichment API
ip_json_response = CLIENT.ip(**IP_PARAMS).json()

# Check for successful response
if ip_json_response["status"] == 200:
    record = ip_json_response["data"]

    # Extract the company id from the response if it exists
    if record["company"]:
        id = record["company"]["id"]

        # Create a parameters JSON object
        COMPANY_PARAMS = {"pdl_id": id}

        # Pass the company id to the Company Enrichment API
        company_json_response = CLIENT.company.enrichment(
            **COMPANY_PARAMS).json()

        # Check for successful response
        if company_json_response["status"] == 200:
            company_record = company_json_response["data"]

            # Write the company record to a JSON file
            with open("company.json", "w") as outfile:
                json.dump(company_record, outfile)

        else:
            print("Company Enrichment API error:",
                  company_json_response["error"])
    else:
        print("No company found for this IP")

else:
    print("IP Enrichment API error:", ip_json_response["error"])

Return All Data Associated with an IP Address

"I want to return all location, IP metadata, company, and person work information associated with an IP address."

# Enriching an IP then returning all associated information
import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying your API key
CLIENT = PDLPY(
    api_key="YOUR API KEY",
)

# Create a parameters JSON object
IP_PARAMS = {
    "ip": "72.212.42.169",
    "return_ip_location": True,
    "return_ip_metadata": True,
    "return_person": True,
    "return_if_unmatched": True
}

# Pass the parameters object to the IP Enrichment API
ip_json_response = CLIENT.ip(**IP_PARAMS).json()

# Check for successful response
if ip_json_response["status"] == 200:
    record = ip_json_response["data"]

    # Extract the company id from the response if it exists
    if record["company"]:
        id = record["company"]["id"]

        # Create a parameters JSON object
        COMPANY_PARAMS = {"pdl_id": id}

        # Pass the company id to the Company Enrichment API
        company_json_response = CLIENT.company.enrichment(
            **COMPANY_PARAMS).json()

        # Check for successful response
        if company_json_response["status"] == 200:
            company_record = company_json_response["data"]

            # Write the company record to a JSON file
            with open("company.json", "w") as outfile:
                json.dump(company_record, outfile)

        else:
            print("Company Enrichment API error:",
                  company_json_response["error"])
    else:
        print("No company found for this IP")

else:
    print("IP Enrichment API error:", ip_json_response["error"])

Lead Search using IP Data

"I want to enrich an IP, then find similar people (same job level, role, and subrole) at the company associated with the IP address."

🚧

Heads Up! Credit Usage

Person Search API calls cost the number of total search results returned.

If you are making a search that could have a large number of results, make sure to use the size parameter to set the maximum number of results and cap your credit usage.

# Enriching an IP then pulling relevant leads/people at the company from the IP
import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying your API key
CLIENT = PDLPY(
    api_key="YOUR API KEY",
)

# Create a parameters JSON object
IP_PARAMS = {
    "ip": "72.212.42.169",
    "return_person": True,
}

# Pass the parameters object to the IP Enrichment API
ip_json_response = CLIENT.ip(**IP_PARAMS).json()

# Check for successful response
if ip_json_response["status"] == 200:
    record = ip_json_response["data"]

    # Extract the company id and person data from the response if it exists
    if record["company"] and record["person"]:
        id = record["company"]["id"]

        ES_QUERY = {
            "query": {
                "bool": {
                    "must": [
                        {"term": {"job_company_id": id}},
                    ]
                }
            }
        }

        job_title_sub_role = record["person"]["job_title_sub_role"]
        if job_title_sub_role:
            ES_QUERY["query"]["bool"]["must"].append(
                {"term": {"job_title_sub_role": job_title_sub_role}})

        job_title_role = record["person"]["job_title_role"]
        if job_title_role:
            ES_QUERY["query"]["bool"]["must"].append(
                {"term": {"job_title_role": job_title_role}})

        job_title_levels = record["person"]["job_title_levels"]
        if job_title_levels and len(job_title_levels) > 0:
            ES_QUERY["query"]["bool"]["must"].append(
                {"terms": {"job_title_levels": job_title_levels}})

        # Create a parameters JSON object
        SEARCH_PARAMS = {
            'query': ES_QUERY,
            'size': 10,
            'pretty': True
        }

        # Pass the params to the Person Search API
        person_search_json_response = CLIENT.person.search(
            **SEARCH_PARAMS).json()

        # Check for successful response
        if person_search_json_response["status"] == 200:
            person_search_record = person_search_json_response["data"]

            # Write the person search record to a JSON file
            with open("person_search.json", "w") as outfile:
                json.dump(person_search_record, outfile)

        else:
            print("Person Search API error:",
                  person_search_json_response["error"])

    else:
        print("No company or person found for this IP")

else:
    print("IP Enrichment API error:", ip_json_response["error"])

Updated about 2 months ago