Introduction

Images are available with the SOCIAL key and up. You can display an image in your application by using the images in the API response. Simply utilize the free to use Pipl thumbnail API with the thumbnail token returned with the image.

This tutorial is to help you to determine the source of an image from the Pipl API response, and address the case when an image is no longer accessible.

Where is the image from?

Some of Pipl Search users wish to only display images that originated from certain data sources. For example, they may want to display a professional Linkedin image over a personal Twitter image in their applications.

The list of images returned from Pipl’s API is vendor neutral. If you activate the sources layer with show_sources=matching (see configuration parameters), you will be able to see source attribution for data fields in a person’s profile. For each image returned for a person, there is a corresponding source in the sources array, indicating the origin with the @name metadata tag (e.g. LinkedIn, Twitter, etc). By searching for the URL of the image in each source, you will be able to cross reference the origin of the image.

For example, let’s search for the email address: [email protected]. This is our query:
http://api.pipl.com/search/[email protected]&key=YOURKEY&show_sources=matching. Note that we appended show_sources=matching which shows only sources that were used to build the Person profile.

Working with the response

There are three important sections to note from the JSON response in order to determine the source of each image:
available data
images array
sources array

Below is an example from a Person response, showing only the information relevant to images.

{
    "@http_status_code": 200, 
    .
 
    "available_data": {
        "premium": {
            "images": 2, 
        }
    }, 
    "person": {
        .
        .
 
        "images": [
            
        ], 
        .
        .
    }, 
    "sources": [
         {
, 
            "@name": "xxx",
            "images": [
                {
                    "url": "", 
                    "thumbnail_token": ""
                }
            ], 
        },
        .
        {...}
    ]
}

From the available_data we determine the number of images returned in the response:

"available_data": {
        "premium": {
            "relationships": 6, 
            .
            .
            "names": 2, 
            "dobs": 1, 
            "images": 2, 
            "genders": 1, 
            "emails": 4, 
            "origin_countries": 1
        }
    },

From the images array in each person object, we can see the source URL for each image, and the thumbnail_token that can be used with Pipl’s thumbnail API.

"images": [
	{
		"url": "http://vignette1.wikia.nocookie.net/smallville/images/e/ea/Buddies_forever.jpg", 
		"thumbnail_token": "AE2861B242686E7BD0CB4D9049298EB7D18FEF66D950E8AB78BCD3F484345CE74536C19A85D0BA3D32DC9E7D1878CD4D341254E7AD129255C6983E6E154C4530A0DAAF665EA325FC0206F8B1D7E0B6B7AD9EBF71FCF610D57D"
	}, 
	{
		"url": "http://vignette3.wikia.nocookie.net/smallville/images/5/55/S10E18-Booster21.jpg", 
		"thumbnail_token": "AE2861B242686E7BD0CB4D9049298EB5D18FEF66D950E8AB78BCD3F484345CE74536C19A85D0BA3D32DC9E7D1878CD4D341254E7AD12C25596CC3E7F51186468FD84B26F5EA234EF1546E7F5CDF7F7F5BA84B228F4F013DD7281"
	}
],

In the sources array we can see the origin of each image. To determine the origin of an image, search through the source array for a source that includes the URL of the image in the ‘images’ field. In the example below, we can determine the image is from the Facebook data source (please note that images from Facebook are no longer publicly available, and the below example is for illustrative purposes only).

"sources": [
      .
      .
      {
           "@id": "5d836a4acc55922e49fc709c7a39e233", 
            "@category": "personal_profiles", 
            "@name": "Facebook", 
            "@origin_url": "http://facebook.com/superman", 
            "@domain": "facebook.com", 
            "@person_id": "cdb74980-718a-4277-82bf-cdd2b30781c8", 
            "@match": 1.0, 
            .
            .
            .
            "images": [
                  {
                        "url": "http://vignette1.wikia.nocookie.net/smallville/images/e/ea/Buddies_forever.jpg", 
                        "thumbnail_token": "AE2861B242686E7BD0CB4D9049298EB7D18FEF66D950E8AB78BCD3F484345CE74536C19A85D0BA3D32DC9E7D1878CD4D341254E7AD129255C6983E6E154C4530A0DAAF665EA325FC0206F8B1D7E0B6B7AD9EBF71FCF610D57D"
                  }, 
                  {
                        "url": "http://vignette3.wikia.nocookie.net/smallville/images/5/55/S10E18-Booster21.jpg", 
                        "thumbnail_token": "AE2861B242686E7BD0CB4D9049298EB5D18FEF66D950E8AB78BCD3F484345CE74536C19A85D0BA3D32DC9E7D1878CD4D341254E7AD12C25596CC3E7F51186468FD84B26F5EA234EF1546E7F5CDF7F7F5BA84B228F4F013DD7281"
                  }
            ],
            .
            .
            .
      },
      .
      .
]

When working with possible person responses, you will need to use show_sources=all in order to see the source layer for possible persons. Besides this change, the same approach is used as with a person response.

Dealing with images that are no longer accessible

Pipl aims to return only URLs to images that are active, however, sometimes due to issues with the image source, the image may no longer be accessible or even exist. These issues may include one or more of the following:

A profile may have been public at a certain stage, however a user changed their privacy settings, so the public profile image is no longer available
A person may have removed the image from their profile or closed down their profile
The website may have removed the image
The social network or URL no longer exists, the entire website is down or the profile was taken down
The social network no longer serves images as public, and requires a special access token to access the image
A website may have changed the way they internally reference images, and the image URL Pipl has a record of becomes invalidated

If the image is no longer accessible when directly using the image URL to retrieve the image, you could get a 403, 404 or 400 HTTP status error response.

The Pipl thumbnail API allows you to select a fallback API token that is used if the first token is not available. If none of the tokens provided to the Pipl thumbnail API are accessible, then a 404 HTTP status code will be returned, and a default Pipl avatar image will be returned.

It is recommended to retrieve the HEAD of the image in your server side application to check if the image is available before displaying this to the user.

To improve your application’s user experience, you may choose to replace Pipl’s thumbnail default avatar with one of your own.