People Data with PHP and JSON

For this guide, we're going to assume the following you're interested in using Datafiniti's people data to develop a sales campaign. Let's say you're a growth marketer that's been tasked with the following:

  1. Collect email addresses of CEOs.
  2. Refine that list to a specific geographic region.

Your environment and data needs:

  1. You're working with PHP.
  2. You want to work with JSON data.

Here are the steps we'll take:

1. Open a code editor

If you want to use PHP to access the Datafiniti API, we're assuming you'll be using a standard code editor to write your PHP code. Open your code editor to get started.

2. Get your API token

The next thing you'll need is your API token. The API token lets you authenticate with Datafiniti API and tells it who you are, what you have access to, and so on. Without it, you can't use the API.

To get your API token, go the Datafiniti Web Portal (https://portal.datafiniti.co), login, and click on your account name and the top-right. From there, you'll see a link to the "My Account" page, which will take you to a page showing your token. Your API token will be a long string of letters and numbers. Copy the API token or store it somewhere you can easily reference.

For security reasons, your API token will be automatically changed whenever you change your password.

πŸ“˜

For the rest of this document, we'll use AAAXXXXXXXXXXXX as a substitute example for your actual API token when showing example API calls.

.

3. Run your first search

The first thing we'll do is do a test search that will give us a sense for what sort of data might be available. Eventually we'll refine our search so that we get back the most relevant data.

Since we want CEOs, let's try a simple search that will just give us people with that title.

Write the following code in your code editor (replace the dummy API token with your real API token):

<?php

$url = 'https://api.datafiniti.co/v4/people/search';

// Set your API parameters here.
$APIToken = 'AAAXXXXXXXXXXXX';
$format = 'JSON';
$query = 'jobTitle:CEO';
$num_records = 1;
$download = false;

$request_body = array(
    'query' => $query,
    'format' => $format,
    'num_records' => $num_records,
    'download' => $download
);

$options = array(
    'http' => array (
        'header'  => "Authorization: Bearer " . $APIToken . "\r\n" . 
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($request_body)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
    echo "Error.";
} else {
    var_dump($result);
}

?>

You should get a response similar to this:

Array
(
    [num_found] => 357
    [total_cost] => 1
    [records] => Array
        (
            [0] => Array
                (
                    [address] => 9855 Melbourne Ave
                    [businessName] => MICHIGAN MARKETING EXTREME LLC
                    [city] => Allen Park
                    [country] => US
                    [dateAdded] => 2018-02-20T00:33:45Z
                    [dateUpdated] => 2018-02-20T00:33:45Z
                    [emails] => Array
                        (
                            [0] => [email protected]
                        )

                    [firstName] => Bill
                    [keys] => Array
                        (
                            [0] => billmeymichiganmarketingextremecom
                        )

                    [lastName] => Mey
                    [jobFunction] => Business Management
                    [jobLevel] => C-Team
                    [jobTitle] => CEO
                    [numEmployeesMin] => 1
                    [numEmployeesMax] => 19
                    [phones] => Array
                        (
                            [0] => 7346190715
                        )
  
                    [postalCode] => 48101
                    [province] => MI

                                    [sourceURLs] => Array
                        (
                            [0] => https://datafiniti.co
                        )

                    [id] => AVwcsllU_7pvs4fzx-yW
                )

        )

)

Let's break down each of the parameters we sent in our request:

API Call Component

Description

"query": "jobTitle:CEO"

query tells the API what query you want to use. In this case, you're telling the API you want to search by jobTitle. Any person that has CEO listed in its jobTitle field will be returned.

"num_records": 1

num_records tells the API how many records to return in its response. In this case, you just want to see 1 matching record.

Now let's dive through the response the API returned:

Response Field

Description

"num_found"

The total number of available records in the database that match your query. If you end up downloading the entire data set, this is how many records you'll use.

"total_cost"

The number of credits this request has cost you. People records have a record cost multiplier tied to them. See pricing.

"records"

The first available matches to your query. If there are no matches, this field will be empty.

Within each record returned, you'll see multiple fields shown. This is the data for each record.

Within the records field, you'll see a single person returned with multiple fields and the values associated with that product. The JSON response will show all fields that have a value. It won't show any fields that don't have a value.

Each product record will have multiple fields associated with it. You can see a full list of available fields in our People Data Schema.

4. Refine your search

Let's say we decided to adjust our sales campaign to only target CEOs in Austin, TX.

Modify your code to look like this:

<?php

$url = 'https://api.datafiniti.co/v4/people/search';

// Set your API parameters here.
$APIToken = 'AAAXXXXXXXXXXXX';
$format = 'JSON';
$query = 'jobTitle:CEO AND province:TX AND city:Austin';
$num_records = 10;
$download = false;

$request_body = array(
    'query' => $query,
    'format' => $format,
    'num_records' => $num_records,
    'download' => $download
);

$options = array(
    'http' => array (
        'header'  => "Authorization: Bearer " . $APIToken . "\r\n" . 
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($request_body)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
    echo "Error.";
} else {
    var_dump($result);
}

?>

This API call is different in a couple ways:

  1. It adds AND province:TX AND city:Austin to narrow down results to just people working in Austin, TX.
  2. It changes "num_records": 1 to "num_records": 10 so we can look at more sample matches.

Notice how Datafiniti lets you construct very refined boolean queries. In the API call above, we're using a combination of AND queries to get exactly what we want.

If you would like to narrow your search to just exact matches you can place the search term in quotation marks.

<?php

$url = 'https://api.datafiniti.co/v4/people/search';

// Set your API parameters here.
$APIToken = 'AAAXXXXXXXXXXXX';
$format = 'JSON';
$query = 'jobTitle:"Product Developer"';
$num_records = 10;
$download = false;

$request_body = array(
    'query' => $query,
    'format' => $format,
    'num_records' => $num_records,
    'download' => $download
);

$options = array(
    'http' => array (
        'header'  => "Authorization: Bearer " . $APIToken . "\r\n" . 
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($request_body)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) {
    echo "Error.";
} else {
    var_dump($result);
}

?>

The above query will only return people with the exact title of Product Developer.

5. Initiate a download of the data

Once we like what we see from the sample matches, it's time to download a larger data set! To do this, we're going to update our code a fair bit (an explanation follows):

<?php

$request_url = 'https://api.datafiniti.co/v4/people/search';

// Set your API parameters here.
$API_token = 'AAAXXXXXXXX';
$format = 'JSON';
$query = 'jobTitle:CEO AND province:TX AND city:Austin';
$num_records = 20;
$download = true;

$request_body = array(
    'query' => $query,
  'num_records' => $num_records,
    'format' => $format,
    'download' => $download
);

$request_options = array(
    'http' => array (
        'header'  => "Authorization: Bearer " . $API_token . "\r\n" . 
                     "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($request_body)
    )
);

// Make the initial API call.
echo "Making initial request...\n";
print_r($request_options);
$request_context  = stream_context_create($request_options);
$request_response = file_get_contents($request_url, false, $request_context);

if ($request_response === FALSE) {

    echo "Error.";
    var_dump($request_response);

} else {

    echo "Download request successful:\n";
    $request_response_array = json_decode($request_response,true);
    print_r($request_response_array);

    $download_id = $request_response_array['id'];
    $download_url = 'https://api.datafiniti.co/v4/downloads/' . $download_id;
    $download_options = array(
        'http' => array (
            'header'  => "Authorization: Bearer " . $API_token . "\r\n",
            'method'  => 'GET'
        )
    );
    $download_status = 'running';
    while ($download_status != 'completed') {
        sleep(10);
        echo "Checking on status: " . $download_url . "\n";
        $download_context  = stream_context_create($download_options);
        $download_response = file_get_contents($download_url, false, $download_context);        
        $download_response_array = json_decode($download_response,true);
        $download_status = $download_response_array['status'];
        echo "Records downloaded: " . $download_response_array['num_downloaded'] . "\n";
    }

    if ($download_status == 'completed') {
        $result_list = $download_response_array['results'];
        for ($i = 0; $i < count($result_list); $i++) {
            $result_link = $result_list[$i];
            $filename = $download_id . "_" . $i . "." . $format;
            file_put_contents($filename, fopen($result_link, 'r'));
            echo "File " . ($i+1) . " out of " . count($result_list) . " saved: " . $filename . "\n";
        }
    }
}

?>

A few things to pay attention to in the above code:

  1. We change num_records from 10 to 20. This will download the first 20 matching records. If we wanted to download all matching records, we would remove num_records. num_records will tell the API to default to all available records.
  2. We changed format from JSON to CSV. We'll want to view the files in CSV format, so it will be easier to look at.
  3. We changed download from false to true.

🚧

If num_records is not specified, ALL of the records matching the query will be downloaded.

Since we've handled multiple steps of the download process in this code, we won't go into the details here, but we do recommend you familiarize yourself with those steps. Checking them out in our People Data with Postman and CSV guide.

🚧

When using the API, you will not receive any warning if you are going past your monthly record limit. Keep a track on how many records you have left by checking your account. You are responsible for any overage fees if you go past your monthly limit.

6. Parse the JSON data

The download code will save one or more result files to your project folder.

πŸ“˜

The JSON data will actually be a text file, instead of a single JSON object. Each line in the text file is a JSON object. We format the data this way because most programming languages won't handle parsing the entire data set as a JSON object with their standard system calls very well.

We'll need to parse the file into an array of JSON objects. We can use code similar to this to handle the parsing:

<?php

// Set the location of your file here
$file = "xxxx_x.txt";

$records = array();

$handle = fopen($file, "r");
if ($handle) {
    while (($line = fgets($handle)) !== false) {
        $records[] = json_decode(($line));
    }
} else {
    echo "Error opening file.";
}

foreach($records as $record) {
    // Edit these lines to do more with the data.
    print_r($record);
}

?>

You can edit the code in the foreach loop above to do whatever you'd like with the data, such as store the data in a database, write it out to your console, etc.