Release NotesDocumentationAPI ReferenceSupportAPI StatusRoadmap
Start Building

Examples - Job Title Enrichment API

Code examples and walkthroughs using the Job Title Enrichment API

Suggest Edits

We've provided code samples in Python, cURL, 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.

📘

See a Bug? Want To See a Specific Example?

Feel free to use the Suggest Edits button in the top right-hand corner of this page to point out any bugs or to request any specific code examples for this API that you'd like to see here.

Basic Usage

"I want to look up information for a job title that I have."

# 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
QUERY_STRING = {"job_title": "pastry chef"}

# Pass the parameters object to the Job Title Enrichment API
response = CLIENT.job_title(**QUERY_STRING)

# Print the API response
print(response.text)

curl -X GET -G \
  'https://api.peopledatalabs.com/v5/job_title/enrich' \
  -H 'X-Api-Key: YOUR API KEY' \
  --data-urlencode 'job_title=pastry chef'

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

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

// Create a parameters JSON object
const queryString = {jobTitle: "pastry chef"}

// Pass the parameters object to the Job Title API
PDLJSClient.jobTitle(queryString).then((data) => {
    // Print the API response
    console.log(data);
}).catch((error) => {
    console.log(error);
});

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

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

# Pass parameters to the Job Title API
response = Peopledatalabs::JobTitle.retrieve("job_title":"pastry chef")

# Print the API response
puts response

package main

import (
    "fmt"
    "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
    queryString := pdlmodel.JobTitleBaseParams{JobTitle: "pastry chef"}
    
    params := pdlmodel.JobTitleParams{
        JobTitleBaseParams: queryString,
    }
    
    // Pass the parameters object to the Job Title API
    response, err := client.JobTitle(context.Background(), params)
    // Check for successful response
    if err == nil {
        // Print the API response
        fmt.Println(response)
    }  
}

import requests

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

# Set the Job Title Enrichment API URL
PDL_URL = "https://api.peopledatalabs.com/v5/job_title/enrich"

# Create a parameters JSON object
QUERY_STRING = {"job_title": "pastry chef"}

# Set headers
HEADERS = {
    'accept': "application/json",
    'content-type': "application/json",
    'x-api-key': API_KEY
}

# Pass the parameters object to the Job Title Enrichment API
response = requests.request("GET", PDL_URL, headers=HEADERS, params=QUERY_STRING)

# Print the API response
print(response.text)

Person Searching Using Job Title Data

"I want to search for people with similar job titles."

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",
)

# Set the maximum number of people to search
MAX_NUM_PEOPLE = 100

# The job title you want to enrich
JOB_TITLE = "supply manager"
# Create a parameters JSON object
QUERY_STRING = {"job_title": JOB_TITLE}

# Pass the parameters object to the Job Title Enrichment API
response = CLIENT.job_title(**QUERY_STRING)

# Check for successful response
if response.status_code == 200:
  # Store enriched job title
  enriched_job_title = response.json()
  # Build list of job titles
  job_titles = enriched_job_title["data"]["similar_job_titles"]
  job_titles.insert(0, JOB_TITLE)
else:
  enriched_job_title = {}
  print(f"Job Title Enrichment Error for [{JOB_TITLE}]: {response.text}")
                                                      
# Person Search matches
employee_matches = {}

# Check for enriched job title
if enriched_job_title:
  # Create an Elasticsearch query
  ES_QUERY = {
  	"query": {
    	"bool": {
        	"must": [
            	{"term": {"location_metro": "detroit, michigan"}},
            	{'term': {'industry': "automotive"}},
            	{"terms": {"job_title": job_titles}}
      		]
    	}
  	}
  }

  # Create a parameters JSON object
  PARAMS = {
  	'query': ES_QUERY,
  	'size': MAX_NUM_PEOPLE
  }
  
  # Pass the parameters object to the Person Search API
  response = CLIENT.person.search(**PARAMS).json()

  # Check for successful response
  if response["status"] == 200:
    # Store matches
  	employee_matches = response["data"]
  else:
  	employee_matches = {}
  	print(f"Person Search Error for [{JOB_TITLE}]: {response}")

  print(f"Found {len(employee_matches)} employee profiles for {JOB_TITLE}.")

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",
)

# Set the maximum number of people to search
MAX_NUM_PEOPLE = 100

# The job title you want to enrich
JOB_TITLE = "supply manager"
# Create a parameters JSON object
QUERY_STRING = {"job_title": JOB_TITLE}

# Pass the parameters object to the Job Title Enrichment API
response = CLIENT.job_title(**QUERY_STRING)

# Check for successful response
if response.status_code == 200:
  # Store enriched job title
  enriched_job_title = response.json()
  # Build list of job titles
  job_titles = enriched_job_title["data"]["similar_job_titles"]
  job_titles.insert(0, JOB_TITLE)
  job_titles_string_rep = ", ".join(
    (f"'{title}'" for title in job_titles)
  )
else:
  enriched_job_title = {}
  print(f"Job Title Enrichment Error for [{JOB_TITLE}]: {response.text}")
                                                      
# Person Search matches
employee_matches = {}

# Check for enriched job title
if enriched_job_title:
  # Create an SQL query
  SQL_QUERY = \
  f"""
    SELECT * FROM person
    WHERE location_metro='detroit, michigan'
    AND industry = 'automotive'
    AND job_title IN ({job_titles_string_rep});
   """

  # Create a parameters JSON object
  PARAMS = {
  	'sql': SQL_QUERY,
  	'size': MAX_NUM_PEOPLE
  }
  
  # Pass the parameters object to the Person Search API
  response = CLIENT.person.search(**PARAMS).json()

  # Check for successful response
  if response["status"] == 200:
    # Store matches
  	employee_matches = response["data"]
  else:
  	employee_matches = {}
  	print(f"Person Search Error for [{JOB_TITLE}]: {response}")

  print(f"Found {len(employee_matches)} employee profiles for {JOB_TITLE}.")

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

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

// Set the maximum number of people to search
const maxNumPeople = 100;

// The job title you want to enrich
const jobTitle = "supply manager";
// Create a parameters JSON object
const queryString = {jobTitle: jobTitle};

// Pass the parameters object to the Job Title API
PDLJSClient.jobTitle(queryString).then((data) => {
    // Store enriched job title
    var enrichedJobTitle = data;
    // Build list of job titles
    var jobTitles = enrichedJobTitle["data"]["similar_job_titles"];
    jobTitles.splice(0, 0, jobTitle);
    
    // Create an Elasticsearch query
    const esQuery = {
        "query": {
            "bool": {
                "must": [
                    {"term": {"location_metro": "detroit, michigan"}},
                    {'term': {'industry': "automotive"}},
                    {"terms": {"job_title": jobTitles}}
      		    ]
    	   }
        }
    }

    // Create a parameters JSON object
    const params = {
        searchQuery: esQuery,
        size: maxNumPeople
    }

    // Pass the parameters object to the Person Search API
    PDLJSClient.person.search.elastic(params).then((data) => {
        // Store matches
        var employeeMatches = data["data"];       
        console.log(`Found ${employeeMatches.length} employee profiles for ${jobTitle}.`); 
    }).catch((error) => {
        console.log(`Person Search Error for [${jobTitle}]:`, error);
    });
       
}).catch((error) => {
    console.log(`Job Title Enrichment Error for [${jobTitle}]:`, error);
});

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

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

// Set the maximum number of people to search
const maxNumPeople = 100;

// The job title you want to enrich
const jobTitle = "supply manager";
// Create a parameters JSON object
const queryString = {jobTitle: jobTitle};

// Pass the parameters object to the Job Title API
PDLJSClient.jobTitle(queryString).then((data) => {
    // Store enriched job title
    var enrichedJobTitle = data;
    // Build list of job titles
    var jobTitles = enrichedJobTitle["data"]["similar_job_titles"];
    jobTitles.splice(0, 0, jobTitle);
    var jobTitlesStringRep = "'" + jobTitles.join("', '") + "'";
    
    // Create an SQL query
    const sqlQuery = `SELECT * FROM person 
                        WHERE location_metro='detroit, michigan'
                        AND industry = 'automotive'
                        AND job_title IN (${jobTitlesStringRep});`

    // Create a parameters JSON object
    const params = {
        searchQuery: sqlQuery,
        size: maxNumPeople
    }

    // Pass the parameters object to the Person Search API
    PDLJSClient.person.search.sql(params).then((data) => {
        // Store matches
        var employeeMatches = data["data"];       
        console.log(`Found ${employeeMatches.length} employee profiles for ${jobTitle}.`); 
    }).catch((error) => {
        console.log(`Person Search Error for [${jobTitle}]:`, error);
    });
       
}).catch((error) => {
    console.log(`Job Title Enrichment Error for [${jobTitle}]:`, error);
});

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

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

# Set the maximum number of people to search
MAX_NUM_PEOPLE = 100

# The job title you want to enrich
JOB_TITLE = "supply manager"

# Pass parameters to the Job Title API
response = Peopledatalabs::JobTitle.retrieve("job_title":JOB_TITLE)

# Check for successful response
if response['status'] == 200
  # Store enriched job title
  enriched_job_title = response
  # Build list of job titles
  job_titles = enriched_job_title['data']['similar_job_titles']
  job_titles.insert(0, JOB_TITLE)
else
  enriched_job_title = {}
  puts "Job Title Enrichment Error for [#{JOB_TITLE}]: #{response}"
end

# Person Search matches
employee_matches = {}

# Check for enriched job title
if !enriched_job_title.nil?
  # Create an Elasticsearch query
  ES_QUERY = {
  	"query": {
    	"bool": {
        	"must": [
            	{"term": {"location_metro": "detroit, michigan"}},
            	{'term': {'industry': "automotive"}},
            	{"terms": {"job_title": job_titles}}
      		]
    	}
  	}
  }

  # Pass parameters to the Person Search API
  response = Peopledatalabs::Search.person(searchType: 'elastic', query: ES_QUERY, size: MAX_NUM_PEOPLE)

  # Check for successful response
  if response['status'] == 200
    # Store matches
  	employee_matches = response['data']
  else
  	employee_matches = {}
  	puts "Person Search Error for [#{JOB_TITLE}]: #{response}"
  end

  puts "Found #{employee_matches.length()} employee profiles for #{JOB_TITLE}."
end

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

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

# Set the maximum number of people to search
MAX_NUM_PEOPLE = 100

# The job title you want to enrich
JOB_TITLE = "supply manager"

# Pass parameters to the Job Title API
response = Peopledatalabs::JobTitle.retrieve("job_title":JOB_TITLE)

# Check for successful response
if response['status'] == 200
  # Store enriched job title
  enriched_job_title = response
  # Build list of job titles
  job_titles = enriched_job_title['data']['similar_job_titles']
  job_titles.insert(0, JOB_TITLE)
  job_titles_string_rep = "'" + job_titles.join("','") + "'"
else
  enriched_job_title = {}
  puts "Job Title Enrichment Error for [#{JOB_TITLE}]: #{response}"
end

# Person Search matches
employee_matches = {}

# Check for enriched job title
if !enriched_job_title.nil?
  # Create an SQL query
  SQL_QUERY = """
    SELECT * FROM person
    WHERE location_metro='detroit, michigan'
    AND industry = 'automotive'
    AND job_title IN (#{job_titles_string_rep});
   """

  # Pass parameters to the Person Search API
  response = Peopledatalabs::Search.person(searchType: 'sql', query: SQL_QUERY, size: MAX_NUM_PEOPLE)

  # Check for successful response
  if response['status'] == 200
    # Store matches
  	employee_matches = response['data']
  else
  	employee_matches = {}
  	puts "Person Search Error for [#{JOB_TITLE}]: #{response}"
  end

  puts "Found #{employee_matches.length()} employee profiles for #{JOB_TITLE}."
end

package main

import (
    "fmt"
    "encoding/json"
    "reflect"
    "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)
    
    // Set the maximum number of people to search
    const maxNumPeople = 100
    
    // The job title you want to enrich
    jobTitle := "supply manager"
    
    var jobTitles []string
    
    // Create a parameters JSON object
    queryString := pdlmodel.JobTitleBaseParams{JobTitle: jobTitle}
    
    params := pdlmodel.JobTitleParams{
        JobTitleBaseParams: queryString,
    }
    
    // Pass the parameters object to the Job Title API
    response, err := client.JobTitle(context.Background(), params)
    
    var enrichedJobTitle map[string][]string

    // Check for successful response
    if err == nil {
        // Convert the API response to JSON
        jsonResponse, jsonErr := json.Marshal(response.Data)
        if jsonErr == nil {
            // Store enriched job title
            json.Unmarshal(jsonResponse, &enrichedJobTitle)
            // Build list of job titles
            jobTitles = enrichedJobTitle["similar_job_titles"]
            jobTitles = append(jobTitles, jobTitle)
        }
    } else {
        fmt.Printf("Job Title Enrichment Error for [%s]:\n\t", jobTitle)
        fmt.Println(err)
   	}
    
    // Person Search matches
    var employeeMatches []pdlmodel.Person

    // Check for enriched job title
    if !reflect.DeepEqual(enrichedJobTitle, pdlmodel.JobTitleResponse{}) {
        // Create an Elasticsearch query
        elasticSearchQuery := map[string]interface{} {
            "query": map[string]interface{} {
                "bool": map[string]interface{} {
                    "must": []map[string]interface{} {
                        {"term": map[string]interface{}{"location_metro": "detroit, michigan"}},
                        {"term": map[string]interface{}{"industry": "automotive"}},
                        {"terms": map[string]interface{}{"job_title": jobTitles}},
                   },
                },
            },
        }
    
        // Create a parameters JSON object
        params := pdlmodel.SearchParams {
            BaseParams: pdlmodel.BaseParams {
                Size: maxNumPeople,
            },
            SearchBaseParams: pdlmodel.SearchBaseParams {
                Query: elasticSearchQuery,
            },
        }

        // Pass the parameters object to the Person Search API
        response, err := client.Person.Search(context.Background(), params)

        // Check for successful response
        if err == nil {
            // Store matches
            employeeMatches = response.Data
            fmt.Printf("Found %d employee profiles for %s.\n", len(employeeMatches), jobTitle)
        } else {
            fmt.Printf("Person Search Error for [%s]:\n\t", jobTitle)
            fmt.Println(err)
        }
    }
}

package main

import (
    "fmt"
    "encoding/json"
    "strings"
    "reflect"
    "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)
    
    // Set the maximum number of people to search
    const maxNumPeople = 100
    
    // The job title you want to enrich
    jobTitle := "supply manager"
    
    var jobTitles []string
    
    // Create a parameters JSON object
    queryString := pdlmodel.JobTitleBaseParams{JobTitle: jobTitle}
    
    params := pdlmodel.JobTitleParams{
        JobTitleBaseParams: queryString,
    }
    
    // Pass the parameters object to the Job Title API
    response, err := client.JobTitle(context.Background(), params)
    
    var enrichedJobTitle map[string][]string
    var jobTitlesStringRep string

    // Check for successful response
    if err == nil {
        // Convert the API response to JSON
        jsonResponse, jsonErr := json.Marshal(response.Data)
        if jsonErr == nil {
            // Store enriched job title
            json.Unmarshal(jsonResponse, &enrichedJobTitle)
            // Build list of job titles
            jobTitles = enrichedJobTitle["similar_job_titles"]
            jobTitles = append(jobTitles, jobTitle)
            jobTitlesStringRep = "'" + strings.Join(jobTitles[:], "','") + "'"
        }
    } else {
        fmt.Printf("Job Title Enrichment Error for [%s]:\n\t", jobTitle)
        fmt.Println(err)
    }
    
    // Person Search matches
    var employeeMatches []pdlmodel.Person

    // Check for enriched job title
    if !reflect.DeepEqual(enrichedJobTitle, pdlmodel.JobTitleResponse{}) {
        // Create an SQL query
        sqlQuery := "SELECT * FROM person" +
                    " WHERE location_metro='detroit, michigan'" +
                    " AND industry = 'automotive'" +
                    " AND job_title IN (" + jobTitlesStringRep + ");"

    
        // Create a parameters JSON object
        params := pdlmodel.SearchParams {
            BaseParams: pdlmodel.BaseParams {
                Size: maxNumPeople,
            },
            SearchBaseParams: pdlmodel.SearchBaseParams {
                SQL: sqlQuery,
            },
        }

        // Pass the parameters object to the Person Search API
        response, err := client.Person.Search(context.Background(), params)

        // Check for successful response
        if err == nil {
            // Store matches
            employeeMatches = response.Data
            fmt.Printf("Found %d employee profiles for %s.\n", len(employeeMatches), jobTitle)
        } else {
            fmt.Printf("Person Search Error for [%s]:\n\t", jobTitle)
            fmt.Println(err)
        }
    }
}

import requests, json

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

# Set the Job Title Enrichment API URL
PDL_JOB_TITLE_ENRICH_URL = "https://api.peopledatalabs.com/v5/job_title/enrich"
# Set the Person Search API URL
PDL_PERSON_SEARCH_URL = "https://api.peopledatalabs.com/v5/person/search"

# Set the maximum number of people to search
MAX_NUM_PEOPLE = 100

# The job title you want to enrich
JOB_TITLE = "supply manager"
# Create a parameters JSON object
QUERY_STRING = {"job_title": JOB_TITLE}

# Set headers
HEADERS = {
  'accept': "application/json",
  'content-type': "application/json",
  'x-api-key': API_KEY
}

# Pass the parameters object to the Job Title Enrichment API
response = requests.request("GET", PDL_JOB_TITLE_ENRICH_URL, 
                            headers=HEADERS, params=QUERY_STRING)

# Check for successful response
if response.status_code == 200:
  # Store enriched job title
  enriched_job_title = response.json()
  # Build list of job titles
  job_titles = enriched_job_title["data"]["similar_job_titles"]
  job_titles.insert(0, JOB_TITLE)
else:
  enriched_job_title = {}
  print(f"Job Title Enrichment Error for [{JOB_TITLE}]: {response.text}")
                                                      
# Person Search matches
employee_matches = {}

# Check for enriched job title
if enriched_job_title:
  # Create an Elasticsearch query
  ES_QUERY = {
  	"query": {
    	"bool": {
        	"must": [
            	{"term": {"location_metro": "detroit, michigan"}},
            	{'term': {'industry': "automotive"}},
            	{"terms": {"job_title": job_titles}},
      		]
    	}
  	}
  }

  # Create a parameters JSON object
  PARAMS = {
  	'query': json.dumps(ES_QUERY),
  	'size': MAX_NUM_PEOPLE
  }

  # Pass the parameters object to the Person Search API
  response = requests.get(PDL_PERSON_SEARCH_URL, headers=HEADERS, params=PARAMS)

  # Check for successful response
  if response.status_code == 200:
    # Store matches
  	employee_matches = response.json()["data"]
  else:
  	employee_matches = {}
  	print(f"Person Search Error for [{JOB_TITLE}]: {response.text}")

  print(f"Found {len(employee_matches)} employee profiles for {JOB_TITLE}.")

import requests, json

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

# Set the Job Title Enrichment API URL
PDL_JOB_TITLE_ENRICH_URL = "https://api.peopledatalabs.com/v5/job_title/enrich"
# Set the Person Search API URL
PDL_PERSON_SEARCH_URL = "https://api.peopledatalabs.com/v5/person/search"

# Set the maximum number of people to search
MAX_NUM_PEOPLE = 100

# The job title you want to enrich
JOB_TITLE = "supply manager"
# Create a parameters JSON object
QUERY_STRING = {"job_title": JOB_TITLE}

# Set headers
HEADERS = {
  'accept': "application/json",
  'content-type': "application/json",
  'x-api-key': API_KEY
}

# Pass the parameters object to the Job Title Enrichment API
response = requests.request("GET", PDL_JOB_TITLE_ENRICH_URL, 
                            headers=HEADERS, params=QUERY_STRING)

# Check for successful response
if response.status_code == 200:
  # Store enriched job title
  enriched_job_title = response.json()
  # Build list of job titles
  job_titles = enriched_job_title["data"]["similar_job_titles"]
  job_titles.insert(0, JOB_TITLE)
  job_titles_string_rep = ", ".join(
    (f"'{title}'" for title in job_titles)
  )

else:
  enriched_job_title = {}
  print(f"Job Title Enrichment Error for [{JOB_TITLE}]: {response.text}")
                                                      
# Person Search matches
employee_matches = {}

# Check for enriched job title
if enriched_job_title:
  # Create an SQL query
  SQL_QUERY = f"""
  SELECT * FROM person
  WHERE location_metro='detroit, michigan'
  AND industry = 'automotive'
  AND job_title IN ({job_titles_string_rep});
  """
    
  # Create a parameters JSON object
  PARAMS = {
  	'sql': SQL_QUERY,
  	'size': MAX_NUM_PEOPLE
  }

  # Pass the parameters object to the Person Search API
  response = requests.get(PDL_PERSON_SEARCH_URL, headers=HEADERS, params=PARAMS)

  # Check for successful response
  if response.status_code == 200:
    # Store matches
  	employee_matches = response.json()["data"]
  else:
  	employee_matches = {}
  	print(f"Person Search Error for [{JOB_TITLE}]: {response.text}")

  print(f"Found {len(employee_matches)} employee profiles for {JOB_TITLE}.")

Updated 4 months ago