NAV
cURL Output

People Pattern Audience Intelligence API

The People Pattern Audience Intelligence API provides access People Pattern’s audience intelligence and model predictions as well as our Portrait Database (PDB). You can query the PDB directly to retrieve portraits with psychographic and demographic attributes pre-appended, or you can submit profile and post data to the API and get it enriched. These are the same services and machine learning-based models which we use in the People Pattern application.

The API described above is stateless, in that we do not store any data provided by you (the client) for application functionality – i.e. the service does not support HTTP PUT, POST, or DELETE requests, at least in spirit. Rather, the API provides access to resources we’ve compiled and maintain.

For the Lookup, Search, Stitching, and Aggregate APIs, the resource accessed is the PDB itself. For the Enrich API, the resource (or resources) is our predictive models. The Execute API fetches data from a variety of sources which differ by job.

Base URL

All URLs referenced in the documentation have the following base:

https://api.peoplepattern.com

The People Pattern API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

All calls require a Content-Type header.

If you’re POSTing json, use:

Content-Type: application/json

If you’re POSTing hocon, use:

Content-Type: application/hocon

Authentication

To authorize, use this code:

# Supply your access token the Authorization header with each request
curl -H "Authorization: $MY_TOKEN" "https://api.peoplepattern.com/lookup?ids=twitter:783214"

# You can also pass the access token as a url parameter
curl "https://api.peoplepattern.com/lookup?ids=twitter:783214&access_token=$MY_TOKEN"

Make sure to replace $MY_TOKEN with your API access token.

HTTP requests to the API are protected with Token Based authentication.

You can find your security token on your account page.

Profiles

Profiles are the primary units of information in the PDB.

JSON Schema

Most requests, responses, and objects have JSON schemas available.

Those types and their schema URLs are introduced throughout the documentation like this:

type schema URL
PDB Profile http://apidocs.peoplepattern.com/schemata/pdb-profile.json

PDB Profiles are loosely based on the Activity Streams format, with modest structural changes and many enhancements.

Enrichments

The structured enrichments appended to profiles include normalized names, aggregated posts, geolocations, demographics, and psychographic attributes.

JSON Schemas

type schema URL
PDB Profile Enrichments http://apidocs.peoplepattern.com/schemata/pdb-profile-enrichments.json

enrichments

field type description
account_type enum predicted account type of the profile. see Account Type Vaues
adult boolean flag for extreme posting of adult content.
influence number calculated influencer score (0-100) of the profile.
interestingness number calculated interestingness score [0-1] of the profile.
spam boolean flag for extreme posting of spam content.

enrichments.demographics

field type description
birthyear number predicted or stated birth year of the profile.
gender string predicted gender of the profile. see Gender values
race string predicted racial identify of the profile. see Race values

enrichments.psychographics

field type description
interests.* map percentage of posts per tagged interests. see Interest values
languages.* map percentage of posts per ISO language code.
sentiment.* map percentage of posts per sentiment classification. see Sentiment values
top_interests array[string] array of top 20 interests. see Interestvalues
top_languages array[string] array of top 20 ISO language code.

enrichments.place

field type description
city boolean true if the place is a city location
state boolean true if the place is a state location
province boolean true if the place is a province location
country boolean true if the place is a country location
type string “City”, “State”, “Provice” or “Country”
geo_name_id number the ID number of the place in the Geonames DB
location location the location record

enrichments.place.location

field type description
dma string the designated market area of the location, if applicable
city string the city name of the location, if applicable
state string the state name of the location, if applicable
state_abbreviation string the state abbreviation, if applicable
utc_offset string the UTC offset in minutes, e.g. “-18000” is Eastern Standard
time_zone string the timezone name, if applicable
metro_area string the metropolitan area, if applicable
continent string the continent of the location, if applicable
language string ISO language code of the country of the location
population number population of the location, if applicable
place_type string “City”, “State”, “Provice” or “Country”
country string the country of the location
country_code string the country code of the location
coordinates coordinates Lat/long coordinates

enrichments.place.location.coordinates

field type
latitude number
longitude number

enrichments.vcard

field type description
name enrichments.vcard.name name
email array of string emails
tel array of string telephone numbers

enrichments.vcard.name

field type description
given_name string given or first name
family_name string family name, surname or last name
fn string full name for display

posts

field type description
devices.* map percentage of posts per device type. see Device Type values
os.* map percentage of posts per operating systems. see Operating System values
top_domains array[string] array of top 20 domains
top_hashtags array[string] array of top 20 hashtags
top_mentions array[string] array of top 20 hashtags

Account Type values

Gender values

Race values

Device Type values

Operating System values

Interest values

Sentiment values

Lookup API

The Lookup API provides access to the Portrait database (PDB) which contains hundreds of millions of social profiles with pre-calculated demographic and psychographic attributes appended to each.
This endpoint supports both HTTP POST and HTTP GET calls.

Profile Lookup

Retrieve one or more profiles from the PDB by submitting their relevant social profile identifiers. If found, an enriched profile (referred to as a portrait) will be returned.

Lookup supports the following services:

To restrict results to just one or just several services, only request ids with an appropriate prefix:

twitter:12345 instagram:56789

When looking up a batch of profiles the response will include each submitted social platform identifier, if a profile is not found in the PDB it is left out of the response.

Resource URI

/lookup

Json Schema

type schema URL
Lookup Request http://apidocs.peoplepattern.com/schemata/LookupRequest.json
Lookup Response http://apidocs.peoplepattern.com/schemata/LookupResponse.json

GET example

curl -X GET -H "Authorization: $MY_TOKEN" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/lookup?ids=twitter:14132201,twitter:119837224&fields=handle"
{
  "twitter:14132201": {
    "name": "chonuff"
  },
  "twitter:119837224": {
    "name": "jasonbaldridge"
  }
}

POST example

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/lookup" \
  -d '{"fields": ["name"],"ids": ["twitter:14132201","twitter:119837224"]}'
{
  "twitter:14132201": {
    "name": "Kenneth Cho"
  },
  "twitter:119837224": {
    "name": "Jason Baldridge"
  }
}

Search API

The Search API allows you to search the Portrait database (PDB) which contains hundreds of millions of social profiles with pre-calculated demographic and psychographic attributes appended to each.

Search supports the following services:

To restrict results to just one or just several services, add a clause to your queryString like:

provider.id:‘twitter’ provider.id:'twitter’ OR provider.id:'instagram’

This endpoint supports both HTTP POST and HTTP GET calls.

Search the PDB by defining a search string using specific demographic and psychographic criteria. This will return 0 or more profiles that match the submitted criteria. The search syntax is based on Lucene

The queryString parameter is the easiest to use, but we also provide a way to search with any valid elasticsearch _search request. Reach out to our support team if your search is more complex than you can express using queryString.

The search results will include all enrichments and predictions for each profile returned. The available enriched set of fields may not be the same across all profiles.

Resource URI

/search

Json Schema

type schema URL
Search Request http://apidocs.peoplepattern.com/schemata/SearchRequest.json
Search Response http://apidocs.peoplepattern.com/schemata/SearchResponse.json

GET Parameters

PARAMETER REQUIRED DESCRIPTION
queryString Yes Lucene formatted query
fields No an array of PDB fields to be returned for each discovered profile. Not including this parameter will return all fields.
limit No the maximum number of profiles to return in the result set
random No if true, return a random set of 'limit’ matching profiles
sortField No a numeric PDB field to be used to sort
sortOrder No ASC or DESC

GET Example

curl -H "Authorization: $MY_TOKEN" -H "Accept: application/json" "https://api.peoplepattern.com/search?queryString=joe&limit=2"
{
    "totalItems": 55659,
    "items": [
    {
        "$schema": "http://streams.peoplepattern.com.s3-website-us-east-1.amazonaws.com/streams-internal/0.11.0/pdb-pojo/pdb-profile.json",
        "type": "profile",
        "name": "Jordyn Derham",
        "handle": "heyjordynnn",
        "location": "",
        "provider": {
            "id": "twitter"
        },
        "twitter": {
            "favourites_count": 8279,
            "followers_count": 654,
            "friends_count": 620,
            "listed_count": 1,
            "statuses_count": 11112,
            "verified": false
        },
        "enrichments": {
            "account_type": "person",
            "spam": false,
            "adult": false,
            "demographics": {
                "birthyear": 1984,
                "age": 33
            },
            "psychographics": {},
            "vcard": {
                "name": {
                    "given_name": "Jordyn",
                    "family_name": "Derham",
                    "fn": "Jordyn Derham"
                }
            },
            "interestingness": 0.5293136029467735,
            "version": "0.11.3.1-RC2",
            "influence": 34
        },
        "id": "twitter:449475865",
        "image": {
            "url": "http://pbs.twimg.com/profile_images/640008864969162752/gRLm24sx_normal.jpg"
        },
        "summary": "osu18 joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe",
        "published": "2011-12-29T04:47:04.000Z",
        "service_id": "449475865",
        "lang": "en",
        "posts": {
            "count": 11112
        }
    }, {
        "$schema": "http://streams.peoplepattern.com.s3-website-us-east-1.amazonaws.com/streams-internal/0.11.0/pdb-pojo/pdb-profile.json",
        "type": "profile",
        "name": "★ joe",
        "handle": "jszulueta",
        "location": "Manila",
        "provider": {
            "id": "twitter"
        },
        "twitter": {
            "favourites_count": 3,
            "followers_count": 48,
            "friends_count": 86,
            "listed_count": 0,
            "statuses_count": 708,
            "verified": false
        },
        "enrichments": {
            "account_type": "person",
            "spam": false,
            "adult": true,
            "demographics": {
                "birthyear": 1977,
                "race": "south-asian",
                "gender": "male",
                "age": 40
            },
            "psychographics": {
                "languages": {
                    "eu": 0.0072992700729927005,
                    "tl": 0.051094890510948905,
                    "en": 0.9197080291970803,
                    "und": 0.0072992700729927005,
                    "it": 0.0072992700729927005,
                    "es": 0.0072992700729927005
                },
                "interests": {
                    "other_sports": 0.0136986301369863,
                    "beauty": 0.00684931506849315,
                    "environmentalism": 0.0136986301369863,
                    "movies": 0.00684931506849315,
                    "humor": 0.0273972602739726,
                    "music": 0.00684931506849315,
                    "health_care": 0.02054794520547945,
                    "design": 0.02054794520547945,
                    "military": 0.0410958904109589,
                    "dating": 0.00684931506849315,
                    "parenting": 0.00684931506849315,
                    "computers": 0.0136986301369863,
                    "shopping": 0.0273972602739726,
                    "local_life": 0.07534246575342465,
                    "gaming": 0.00684931506849315,
                    "beverages": 0.02054794520547945,
                    "business": 0.0136986301369863,
                    "current_events": 0.00684931506849315,
                    "consumer_electronics": 0.03424657534246575,
                    "food": 0.0410958904109589,
                    "outdoor_recreation": 0.00684931506849315,
                    "religion": 0.02054794520547945,
                    "crafts": 0.00684931506849315,
                    "multimedia": 0.3561643835616438,
                    "science": 0.02054794520547945,
                    "toys_and_games": 0.00684931506849315,
                    "school_life": 0.00684931506849315,
                    "travel": 0.1506849315068493,
                    "family": 0.0136986301369863
                },
                "sentiment": {
                    "negative": 0.031496062992125984,
                    "neutral": 0.7637795275590551,
                    "positive": 0.2047244094488189
                },
                "top_languages": ["en", "tl", "es"],
                "top_interests": ["multimedia", "travel", "local_life", "food", "military"]
            },
            "place": {
                "city": true,
                "geo_name_id": 1701668,
                "type": "City",
                "name": "Manila, Philippines",
                "location": {
                    "city": "Manila",
                    "state": "Metro Manila",
                    "state_abbreviation": "NCR",
                    "time_zone": "Asia/Manila",
                    "metro_area": "Quezon City, Philippines",
                    "continent": "AS",
                    "population": 1600000,
                    "place_type": "City",
                    "country": "Philippines",
                    "country_code": "PH",
                    "coordinates": {
                        "longitude": 120.9822,
                        "latitude": 14.6042
                    }
                },
                "global_metro_area": "Manila, Philippines"
            },
            "vcard": {
                "name": {
                    "given_name": "Joe",
                    "family_name": "Zulueta",
                    "fn": "Joe Zulueta"
                }
            },
            "interestingness": 0.6580114462803627,
            "version": "0.11.3.1-RC2",
            "influence": 19
        },
        "id": "twitter:130573602",
        "image": {
            "url": "http://pbs.twimg.com/profile_images/491912407841644544/7dD2PrDr_normal.jpeg"
        },
        "summary": "joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe joe",
        "published": "2010-04-07T17:56:08.000Z",
        "service_id": "130573602",
        "lang": "en",
        "posts": {
            "top_hashtags": ["3d", "fps", "mobile", "pg3d", "pixelgun", "pixelgun3d", "shooter", "HiddenRisks", "TheSMStoreMakati3DS", "WaltDisney", "gifersation"],
            "os": {
                "android": 0.4444444444444444,
                "ios": 0.5555555555555556
            },
            "devices": {
                "desktop": 0.04,
                "mobile": 0.96
            },
            "top_domains": ["fb.me", "4sq.com", "goo.gl", "instagr.am", "www.viber.com", "bit.ly", "huff.to", "ph.sharings.cc", "play.google.com", "wechat.com"],
            "count": 708,
            "top_mentions": ["twitter:960481315", "twitter:122302784", "twitter:14120151", "twitter:2166412230", "twitter:2576461322", "twitter:15092616", "twitter:3746042353", "twitter:71983360", "twitter:106915372", "twitter:14511951", "twitter:326380075", "twitter:335942140", "twitter:347258974", "twitter:871351657"]
        }
    }
    ]
}

POST Example

curl -H "Authorization: $MY_TOKEN" -X POST -H "Accept: application/json" -H "Content-Type: application/json" "https://api-qa.peoplepattern.com/search" -d '{"queryString":"john", "limit":"2","random":"true"}'
{
    "totalItems": 55659,
    "items": [
    {
        "$schema": "http://streams.peoplepattern.com.s3-website-us-east-1.amazonaws.com/streams-internal/0.11.0/pdb-pojo/pdb-profile.json",
        "type": "profile",
        "name": "joe-joint",
        "handle": "joe-joint",
        "provider": {
            "id": "tumblr"
        },
        "twitter": {},
        "enrichments": {
            "account_type": "person",
            "spam": false,
            "adult": false,
            "demographics": {
                "birthyear": 1990,
                "race": "white",
                "gender": "male",
                "age": 27
            },
            "psychographics": {},
            "vcard": {
                "name": {
                    "given_name": "Joe-joint",
                    "family_name": "Joe",
                    "fn": "Joe-joint Joe"
                }
            },
            "interestingness": 0.7642813799014391,
            "version": "0.11.3.1-RC2"
        },
        "id": "tumblr:joe-joint",
        "image": {
            "url": "https://api.tumblr.com/v2/blog/joe-joint.tumblr.com/avatar"
        },
        "summary": "Rocko floyd zeplin",
        "url": "http://joe-joint.tumblr.com/",
        "published": "2014-07-08T04:25:50.117Z",
        "service_id": "joe-joint",
        "posts": {}
    }, {
        "$schema": "http://streams.peoplepattern.com.s3-website-us-east-1.amazonaws.com/streams-internal/0.11.0/pdb-pojo/pdb-profile.json",
        "type": "profile",
        "name": "joe-wagner",
        "handle": "joe-wagner",
        "provider": {
            "id": "tumblr"
        },
        "twitter": {},
        "enrichments": {
            "account_type": "person",
            "spam": false,
            "adult": false,
            "demographics": {
                "birthyear": 1987,
                "race": "white",
                "gender": "male",
                "age": 30
            },
            "psychographics": {},
            "vcard": {
                "name": {
                    "given_name": "Joe-wagner",
                    "family_name": "Wagner",
                    "fn": "Joe-wagner Wagner"
                }
            },
            "interestingness": 0.8920150138040867,
            "version": "0.11.3.1-RC2"
        },
        "id": "tumblr:joe-wagner",
        "image": {
            "url": "https://api.tumblr.com/v2/blog/joe-wagner.tumblr.com/avatar"
        },
        "summary": "Asshole extraordinaire.",
        "url": "http://joe-wagner.tumblr.com/",
        "published": "2014-09-02T00:06:17.338Z",
        "service_id": "joe-wagner",
        "posts": {}
    }
  ]
}

Aggregate API

The Aggregate API allows you to retrieve aggregate insights from the Portrait database (PDB) which contains hundreds of millions of social profiles with pre-calculated demographic and psychographic attributes appended to each.

Aggregate supports the following services:

Aggregate Profiles

Get aggregate insights for a set of profiles by submitting their social profile identifiers to the PDB.
Aggregate data is returned for both demographic and psychographic attributes.

Resource URI

/aggregate

Json Schema

type schema URL
Aggregate Request http://apidocs.peoplepattern.com/schemata/AggregateRequest.json
Aggregate Response http://apidocs.peoplepattern.com/schemata/AggregateResponse.json

Aggregate profile attributes

Aggregate supports all enum, numeric, date-time, array, and map fields defined on a PDB profile.

Note that the fields to aggregate must be requested in flattened format (see below).

Also note that map fields must be requested using syntax like posts.os.* and posts.devices.*.

GET Example

curl -X GET -H "Authorization: $MY_TOKEN" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/aggregate?fields=enrichments.demographics.race,enrichments.demographics.birthyear,enrichments.account_type&ids=twitter:14132201,twitter:119837224,twitter:391705374,twitter:20092104"
{
    "enrichments.account_type": {
        "person": 1.0
    },
    "enrichments.demographics.gender": {
        "male": 1.0
    },
    "enrichments.demographics.race": {
        "white": 0.6666666666666666,
        "east-asian": 0.3333333333333333
    },
    "enrichments.demographics.birthyear": {
        "1975": 0.5,
        "1972": 0.5
    }
}

POST Example

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/aggregate" \
  -d '{"fields":["enrichments.demographics.race","enrichments.demographics.birthyear","enrichments.account_type""enrichments.demographics.gender"], "ids":["twitter:14132201","twitter:119837224","twitter:391705374","twitter:20092104"]}'

{
    "enrichments.account_type": {
        "person": 1.0
    },
    "enrichments.demographics.gender": {
        "male": 1.0
    },
    "enrichments.demographics.race": {
        "white": 0.6666666666666666,
        "east-asian": 0.3333333333333333
    },
    "enrichments.demographics.birthyear": {
        "1975": 0.5,
        "1972": 0.5
    }
}

Search/Aggregate Profiles

We also offer aggregation based on search criteria. The queryString parameter is the easiest to use, but we also provide a way to search with any valid elasticsearch _search request. Reach out to our support team if your search is more complex than you can express using queryString.

Resource URI

/aggregatesearch

Json Schema

type schema URL
AggregateSearch Request http://apidocs.peoplepattern.com/schemata/AggregateSearchRequest.json
AggregateSearch Response http://apidocs.peoplepattern.com/schemata/AggregateSearchResponse.json

GET Example

curl -X GET -H "Authorization: $MY_TOKEN" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/aggregate?fields=enrichments.demographics.race,enrichments.demographics.birthyear,enrichments.account_type,enrichments.demographics.gender&queryString=john" \
{
    "enrichments.account_type": {
        "entertainment": 1.8391506376973333E-4,
        "person": 0.9947953288076048,
        "organization": 0.005020756128625441
    },
    "enrichments.demographics.gender": {
        "female": 0.011415977072219231,
        "male": 0.9885840229277808
    },
    "enrichments.demographics.race": {
        "middle-eastern": 2.807261232695993E-4,
        "white": 0.8984420511505714,
        "south-asian": 0.001572390829180588,
        "hispanic": 0.051822366894438865,
        "black": 0.034495236580723364,
        "east-asian": 0.013387228421816152
    },
    "enrichments.demographics.birthyear": {
        "1990": 0.021262022202317505,
        "1987": 0.049928869902849664,
        "1986": 0.06093680972395037,
        "1997": 0.02167137489816845,
        "1985": 0.06690282129120378,
        "1996": 0.03187276831853314,
        "1984": 0.0660516919235929,
        "1995": 0.033445331150118954,
        "1983": 0.05902784814230883,
        "1994": 0.028342607941442298,
        "1982": 0.04858732789961537,
        "1993": 0.023130453814072815,
        "1981": 0.037976581783399736,
        "1992": 0.01916662275919929,
        "1980": 0.028820861586099842,
        "1991": 0.018692422111530372,
        "1979": 0.021675427895157074,
        "1968": 0.018218221463861452,
        "1989": 0.027896778272693743,
        "1988": 0.03941944871134961
    }
}

POST Example

curl -X GET -H "Authorization: $MY_TOKEN" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/aggregate" \
  -d '{"queryString":"jill","fields":["enrichments.demographics.race","enrichments.demographics.birthyear","enrichments.account_type","enrichments.demographics.gender"]}'
{
    "enrichments.account_type": {
        "entertainment": 1.7386356451918822E-4,
        "person": 0.9961275842447999,
        "organization": 0.003698552190680913
    },
    "enrichments.demographics.gender": {
        "female": 0.9968667493717593,
        "male": 0.003133250628240608
    },
    "enrichments.demographics.race": {
        "middle-eastern": 3.677214142565592E-5,
        "white": 0.9725128242843222,
        "south-asian": 3.1256320211807534E-4,
        "hispanic": 0.01000202246777841,
        "black": 0.009781389619224475,
        "east-asian": 0.007354428285131185
    },
    "enrichments.demographics.birthyear": {
        "1987": 0.028461114175399888,
        "1976": 0.014120242691671264,
        "1986": 0.04569773855488141,
        "1985": 0.08066740209597352,
        "1984": 0.11265857694429122,
        "1983": 0.115857694429123,
        "1972": 0.015747380033094317,
        "1982": 0.10157198014340872,
        "1971": 0.0163265306122449,
        "1981": 0.0753723110865968,
        "1970": 0.017539988968560398,
        "1980": 0.050082735797021515,
        "1969": 0.019332597904026475,
        "1979": 0.03143960286817429,
        "1968": 0.017402095973524545,
        "1978": 0.023965802537231108,
        "1967": 0.01643684500827358,
        "1977": 0.0197738554881412,
        "1988": 0.01693325979040265,
        "1966": 0.0151130722559294
    }
}

Execute API

The Execute API allows for programmatic, real-time access to some of People Pattern’s most computationally heavy analytics processes.

Execute supports the following services:

The following endpoints are used to interact with the Execute API.

Workflow

The basic workflow is this:

  1. Validate a job request using the /estimate endpoint.

  2. Kick off a job using the /execute endpoint.

  3. Using the job hash that the above step returns, periodically check the status of your job using the /status endpoint.

  4. When the status endpoint reports that your job has finished, retrieve the resulting JSON using the /resources endpoint.

Execute

This is the endpoint used to kick off jobs. To start a job, send an HTTP POST request to this endpoint, specifying one of the service_type values enumerated below. You’ll need the following headers in your HTTP request:

Accept: application/json

If the body of your POST request is a JSON file:

Content-Type: application/json

Or, if the body of your POST request is a CONF file:

Content-Type: application/hocon

Resource URI

/execute/{job_type}

Json Schema

type schema URL
Execute Response http://apidocs.peoplepattern.com/schemata/ExecuteResponse.json

POST example (json)

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/{job_type}" \
  -d '{POST_BODY}'
{"execution":"{job_hash}","status":"SUBMITTED"}

POST example (hocon)

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/hocon" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/{job_type}" \
  -d '{POST_BODY}'
{"execution":"{job_hash}","status":"SUBMITTED"}

Estimate

Estimate determines whether a job request is valid, and estimates how long the job will take to begin and then to complete execution.

Resource URI

/estimate

Json Schema

type schema URL
Estimate Request http://apidocs.peoplepattern.com/schemata/EstimateRequest.json
Estimate Response http://apidocs.peoplepattern.com/schemata/EstimateResponse.json

The potential errors and warnings returned differ by job type.

POST example

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: {application/json} OR {application/hocon}" \
  -H "Accept: application/json" \
  'https://api.peoplepattern.com/estimate/{job_type}' \
  -d '{POST_BODY}'
{"valid": true, "runMs":300000, "waitMs":300000}
{"errors":["Invalid job type"]}
{"errors":["Maximum of 1000 ids may be provided"]}
{"valid": true, "runMs":300000, "waitMs":300000, "warnings":["At least 50 ids must be provided"]}
{"valid": false, "errors":["A list of ids must be present"]}

Status

The Status endpoint used to check the status of jobs you’ve already started. To check job status, send an HTTP GET request to this endpoint specifying your job hash from the /execute endpoint as a URL parameter.

Resource URI

/status?execution={job_hash}

Json Schema

type schema URL
Status Request http://apidocs.peoplepattern.com/schemata/StatusRequest.json
Status Response http://apidocs.peoplepattern.com/schemata/StatusResponse.json

GET example

curl -X GET -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/status?execution={job_hash}"
{"execution":"{job_hash}","status":"RUNNING"}
{"execution":"{job_hash}","status":"FINISHED"}

Result

The Result endpoint used to retrieve the results of a job after the /status endpoint indicates that it has finished executing. To retrieve these results, send an HTTP GET request to this endpoint, specifying your job hash. Note that calling this endpoint for a job which has not yet finished will result in an empty response body. The content of an appropriate response will depend on which kind of job is being executed, but will always be in JSON form.

Resource URI

/resources/{job_hash}

GET example

curl -X GET -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/resources/{job_hash}"

Jobs

The jobs listed here represent the current set of reports or analysis the supported by the execute API.

Analyze Public Profiles

To run the Analyze Public Profiles stream for one or more users, make an HTTP POST request to the Analyze Public Profiles endpoint.

/AnalyzePublicProfiles

Json Schema

type schema URL
AnalyzePublicProfilesRequest http://apidocs.peoplepattern.com/schemata/AnalyzePublicProfilesRequest.json

POST example (json)

curl  \
  -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/AnalyzePublicProfiles" \
  -d '{"ids":["twitter:116679528","twitter:118710202", "twitter:119772680"]}'

POST example (hocon)

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/hocon" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/AnalyzePublicProfiles" \
  -d 'ids = ["twitter:116679528","twitter:118710202", "twitter:119772680"]'

Audience Influencers

To get an Audience Influencers report for one or more users, make an HTTP POST request to the Audience Influencers endpoint.

/AudienceInfluencers

Json Schema

type schema URL
AudienceInfluencersReportRequest http://apidocs.peoplepattern.com/schemata/AudienceInfluencersReportRequest.json
AudienceInfluencersReportResult http://apidocs.peoplepattern.com/schemata/AudienceInfluencersReportResult.json

POST example (json)

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/AudienceInfluencers" \
  -d '{"ids":["twitter:116679527","twitter:118710202", "twitter:119772680"]}'

POST example (hocon)

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/hocon" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/AudienceInfluencers" \
  -d 'ids = ["twitter:116679528","twitter:118710202", "twitter:119772680"]'

External Influencers

To get an External Influencers report for one or more users, make an HTTP POST request to the External Influencers endpoint.

/ExternalInfluencers

Json Schema

type schema URL
ExternalInfluencersReportRequest http://apidocs.peoplepattern.com/schemata/ExternalInfluencersReportRequest.json
ExternalInfluencersReportResult http://apidocs.peoplepattern.com/schemata/ExternalInfluencersReportResult.json

POST example (json)

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/ExternalInfluencers" \
  -d '{"ids":["twitter:116679527","twitter:118710202", "twitter:119772680"]}'

POST example (hocon)

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/hocon" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/ExternalInfluencers" \
  -d 'ids = ["twitter:116679528","twitter:118710202", "twitter:119772680"]'

Follower Breakdown

To get a follower breakdown for one or more users, make an HTTP POST request to the Follower Breakdown endpoint.

/FollowerBreakdown

Json Schema

type schema URL
FollowerBreakdownReportRequest http://apidocs.peoplepattern.com/schemata/FollowerBreakdownReportRequest.json
FollowerBreakdownReportResult http://apidocs.peoplepattern.com/schemata/FollowerBreakdownReportResult.json

POST example (json)

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/FollowerBreakdown" \
  -d '{"ids":["twitter:116679527","twitter:118710202", "twitter:119772680"]}'

POST example (hocon)

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/hocon" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/execute/FollowerBreakdown" \
  -d 'ids = ["twitter:116679528","twitter:118710202", "twitter:119772680"]'

Enrich API

The Enrich API provides access to our audience intelligence and machine-learned based models used to extract personal attributes, like demographics and location information from profile and post data.

This API takes as input a serialized as JSON object, and echoes that content back in the response along with predicted enrichments. This allows you to include an identifier which gets returned in the response and may be used as a reference id.

Profile Enrich

When enriching a profile the profile data structure is passed back to the client along with the profile enrichments.

Resource URI enrich-profile

/profile

HTTP POST

To enrich a profile, make an HTTP POST request to Profile Enrich endpoint.
We use the HTTP POST method, since some clients do not allow you to send request bodies with HTTP GET requests.

POST PARAMETERS

PARAMETER REQUIRED DESCRIPTION
body Yes a profile object or an array of profile objects

Enrich a single profile

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/profile" \
  -d '{"name":"Joe User", "username": "juser", "description": "my profile", "location": "Boston, USA"}'

TODO: rerun this, response format out of date

{
  "name": "Joe User",
  "username": "juser",
  "description": "my profile",
  "location": "Boston, USA",
  "peoplepattern": {
    "account_type": "person",
    "spam": false,
    "adult": false,
    "vcard": {
      "name": {
        "given-name": "Joe",
        "family-name": "User",
        "fn": "Joe User"
      },
      "email": []
    },
    "demographics": {
      "birthyear": 1985,
      "gender": "male",
      "race": "white"
    },
    "place": {
      "name": "Boston, Massachusetts",
      "city": true,
      "geo_name_id": 4930956,
      "type": "City",
      "location": {
        "dma": "Boston, MA-Manchester, NH",
        "city": "Boston",
        "state": "Massachusetts",
        "state_abbreviation": "MA",
        "utc_offset": "-18000",
        "time_zone": "America/New_York",
        "metro_area": "Boston-Cambridge-Newton, MA-NH",
        "continent": "NA",
        "language": "en",
        "population": 617594,
        "place_type": "City",
        "country": "United States",
        "country_code": "US",
        "coordinates": {
          "longitude": 42.35843,
          "latitude": -71.05977
        }
      }
    },
    "extended_demographics": {},
    "interestingness": 0.8431624560581947,
    "_meta": {
      "source": "current-models",
      "model_version": "0.11-pre4",
      "predict_fields": [
        "name",
        "username",
        "description",
        "location"
      ]
    }
  }
}

When passing a single profile to the enrich profile endpoint, the profile data structure is passed back to the client with a peoplepattern field filled with profile enrichments.

Enrich a batch of profiles

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/profile" \
  -d '[{"name":"Joe User", "username": "juser", "description": "my profile", "location": "Boston, USA"}, {"name": "Mary Brown", "username": "mbrown", "description": "This is Marys profile"}]'
[
  {
    "status": "success",
    "code": 200,
    "result": {
      "name": "Joe User",
      "username": "juser",
      "description": "my profile",
      "location": "Boston, USA",
      "peoplepattern": {
        "account_type": "person",
        "spam": false,
        "adult": false,
        "vcard": {
          "name": {
            "given-name": "Joe",
            "family-name": "User",
            "fn": "Joe User"
          },
          "email": []
        },
        "demographics": {
          "birthyear": 1985,
          "gender": "male",
          "race": "white"
        },
        "place": {
          "name": "Boston, Massachusetts",
          "city": true,
          "geo_name_id": 4930956,
          "type": "City",
          "location": {
            "dma": "Boston, MA-Manchester, NH",
            "city": "Boston",
            "state": "Massachusetts",
            "state_abbreviation": "MA",
            "utc_offset": "-18000",
            "time_zone": "America/New_York",
            "metro_area": "Boston-Cambridge-Newton, MA-NH",
            "continent": "NA",
            "language": "en",
            "population": 617594,
            "place_type": "City",
            "country": "United States",
            "country_code": "US",
            "coordinates": {
              "longitude": 42.35843,
              "latitude": -71.05977
            }
          }
        },
        "extended_demographics": {},
        "interestingness": 0.8431624560581947,
        "_meta": {
          "source": "current-models",
          "model_version": "0.11-pre4",
          "predict_fields": [
            "name",
            "username",
            "description",
            "location"
          ]
        }
      }
    }
  },
  {
    "status": "success",
    "code": 200,
    "result": {
      "name": "Mary Brown",
      "username": "mbrown",
      "description": "This is Mary's profile",
      "peoplepattern": {
        "account_type": "person",
        "spam": false,
        "adult": false,
        "vcard": {
          "name": {
            "given-name": "Mary",
            "family-name": "Brown",
            "fn": "Mary Brown"
          },
          "email": []
        },
        "demographics": {
          "birthyear": 1962,
          "gender": "female",
          "race": "white"
        },
        "extended_demographics": {},
        "interestingness": 0.9613207296903373,
        "_meta": {
          "source": "current-models",
          "model_version": "0.11-pre4",
          "predict_fields": [
            "name",
            "username",
            "description"
          ]
        }
      }
    }
  }
]

When passing a batch of profiles to the enrich profile endpoint, the client receives a batch of responses. Since each profile request may succeed or fail individually, the batch of responses included their own meta-data with respect to the response status.

Error Sample

To see a comprehensive list of error status returned the the People Pattern Audience Intelligence API please see the Errors section.
Here we have displayed what a same error response would look like from the Enrich API.

Example invalid format call with output

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/profile" \
  -d '[{}]'

[{"status":"error","code":400,"error":{"input":{},"message":"No valid fields provided for profile content"}}]

Post Enrich

When enriching a post the post data structure is passed back to the client along with the profile enrichments.

Resource URI enrich-post

/post

HTTP POST

To enrich a post, make an HTTP POST request to Post Enrich endpoint.
We use the HTTP POST method, since some clients do not allow you to send request bodies with HTTP GET requests.

POST PARAMETERS

PARAMETER REQUIRED DESCRIPTION
body Yes a post object or a array of post objects

Post (input)

A social media post or other text may be passed to the Enrich API as a JSON object with a string-valued text field

field type
text string

JSON objects containing other fields may be used, and other fields are provided back to the client in enriched post output

Post enrichments

Sample post enrichments as JSON

{
  "interests": [
    "science"
  ],
  "languages": [
    "en"
  ],
  "sentiment": "neutral"
}

Post enrichments consist of a set of predicted interest topics, predicted languages and predicted sentiment

field type description
interests array of string interest topics
languages array of string ISO 639-1 two letter language codes
sentiment string “positive”, “negative” or “neutral”

Enrich a single post

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/post" \
  -d '{"text":"Bowling tonight? or kung-fu?"}'
{
  "text": "Bowling tonight? or kung-fu?",
  "peoplepattern": {
    "interests": [
      "leisure_sports"
    ],
    "languages": [
      "en"
    ],
    "sentiment": "neutral",
    "interestingness": 0.7085509373685894
  }
}

When passing a single post to the enrich post endpoint, the post data structure is passed back to the client with a peoplepattern field filled with post enrichments.

Enrich a batch of posts

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/post" \
  -d '[{"text":"Bowling tonight? or kung-fu?"},{"text":"I love bowling with friends"},{"text":"But I also love eating at home with the family"}]'
[
  {
    "status": "success",
    "code": 200,
    "result": {
      "text": "Bowling tonight? or kung-fu?",
      "peoplepattern": {
        "interests": [
          "leisure_sports"
        ],
        "languages": [
          "en"
        ],
        "sentiment": "neutral",
        "interestingness": 0.7085509373685894
      }
    }
  },
  {
    "status": "success",
    "code": 200,
    "result": {
      "text": "I love bowling with friends",
      "peoplepattern": {
        "interests": [
          "leisure_sports"
        ],
        "languages": [
          "en"
        ],
        "sentiment": "positive",
        "interestingness": 0.5522605037296693
      }
    }
  },
  {
    "status": "success",
    "code": 200,
    "result": {
      "text": "But I also love eating at home with the family",
      "peoplepattern": {
        "interests": [
          "family"
        ],
        "languages": [
          "en"
        ],
        "sentiment": "positive",
        "interestingness": 0.5893891902193789
      }
    }
  }
]

When passing a batch of posts to the enrich post endpoint, the client receives a batch of responses. Since each post request may succeed or fail individually, the batch of responses included their own meta-data with respect to the response status.

Error Sample

To see a comprehensive list of error status returned the the People Pattern Audience Intelligence API please see the Errors section.
Here we have displayed what a same error response would look like from the Enrich API.

Example invalid format call with output

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/post" \
  -d '[{}]'

[{"status":"error","code":400,"error":{"input":{},"message":"No valid fields provided for profile content"}}]

Stitching API

The Stitching API exposes a model which attempts to match an individual’s name, location, and/or email address to a Twitter account. People Pattern’s stitching algorithms process, identify, score and match social profiles to individuals, adding dimensions of customer attributes previously unattainable

Stitching supports the following services:

Stitch (input)

Persons are objects containing any of the following fields. These are provided to the stitch Stitching API endpoints

field type description
name string the first and last name of the person
email string the person’s email address, typically the same one used for the social account(s)
location string the text representation of the person’s location

All fields are optional, but a person object containing none of these fields is considered a bad request, and the more fields submitted increase the quality of matches returned.

Stitch a single record

When stitching a person record the original person record is passed back along with an array of possible matches.

Resource URI stitch

/stitch

HTTP POST

To stitch a person record to a social profile, make an HTTP POST request to Stitching endpoint. The appropriate headers and default body schema can be seen in the example request in the sidebar.

POST PARAMETERS

PARAMETER REQUIRED DESCRIPTION
body Yes a person record or an array of person objects

Stitch a single person record

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/stitch" \
  -d '{"query":{"name":"Elias Ponvert","location":"Austin, Texas"}}'
{
  "hits": {
    "hits": [
      {
        "handle": "eponvert",
        "provider": {
          "id": "twitter"
        },
        "service_id": "61546029",
        "id": "twitter:61546029",
        "_score": 10
      }
    ],
    "total": 1
  }
}

Each match will contain a score indicating the confidence of that match. When passing a single person record to the stitch endpoint, the array of results are passed back to the client with a score indicating the confidence of each match.

Stitch a batch of records

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  'https://api.peoplepattern.com/stitch' \
  -d '[{"query":{"name":"Elias Ponvert","location":"Austin, Texas"}},{"query":{"name":"Jason Baldridge","location":"Austin, Texas"}}]'
[
  {
    "hits": {
      "hits": [
        {
          "handle": "eponvert",
          "provider": {
            "id": "twitter"
          },
          "service_id": "61546029",
          "id": "twitter:61546029",
          "_score": 10
        }
      ],
      "total": 1
    }
  },
  {
    "hits": {
      "hits": [
        {
          "handle": "jasonbaldridge",
          "provider": {
            "id": "twitter"
          },
          "service_id": "119837224",
          "id": "twitter:119837224",
          "_score": 10
        }
      ],
      "total": 1
    }
  }
]

When passing a batch of person records to the stitch endpoint, POST an array of query JSON objects rather than just a single one.

Requesting Additional Fields

curl -X POST -H "Authorization: $MY_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "https://api.peoplepattern.com/stitch" \
  -d '{"query":{"name":"Elias Ponvert","location":"Austin, Texas"},"fields":["name", "twitter", "peoplepattern"]}'
{
  "hits": {
    "hits": [
      {
        "peoplepattern": {
          "account_type": "person",
          "birthyear": 1979,
          "gender": "male",
          "race": "white",
          "interestingness": 0.9938160676130328,
          "ageQuantiles": [
            29,
            29.25,
            29.5,
            29.75,
            30,
            30.25,
            30.5,
            31.303387682248616,
            32.860457271189546
          ],
          "numAgeQuantiles": 9,
          "adult": false,
          "spam": false,
          "version": "0.10",
          "age": 37
        },
        "name": "elias ponvert",
        "twitter": {
          "friends_count": 1233,
          "listed_count": "27",
          "screen_name": "eponvert",
          "statuses_count": 857,
          "favourites_count": 87,
          "followers_count": 417,
          "verified": false
        },
        "_score": 10
      }
    ],
    "total": 1
  }
}

You can request that the response you receive be annotated with additional fields for each match found. Those additional fields are:

"name": Requesting this field simply appends the matched user’s “name” field from Twitter to the response.

"twitter": Requesting this field appends other basic information about the Twitter account such as number of followers, number of tweets, whether the user is “Verified”, etc.

"peoplepattern": Requesting this field appends some basic predictions from our other models to the response. This includes predictions of account type, some demographic information, and an “interestingness” score.

Errors

The People Pattern API uses the following error codes:

Error Code Meaning
400 Bad Request – Malformed request
401 Unauthorized – Your API key is wrong
404 Not Found – The requested resource is not available on the API
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The resource requested has been removed from our servers
429 Too Many Requests – Too many concurrent requests are being made by your client
500 Internal Server Error – Service side error – please contact us a api-help@peoplepattern.com
503 Service Unavailable – Service is offline for maintenance