pipl

package module
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 3, 2020 License: MIT Imports: 11 Imported by: 0

README

go-pipl

go-pipl is a simple golang wrapper to help find people using the pipl.com API.

Go Build Status Report Codacy Badge Release standard-readme compliant GoDoc

Table of Contents

Installation

go-pipl requires a supported release of Go.

$ go get -u github.com/mrz1836/go-pipl

Documentation

You can view the generated documentation here.

Features
  • Complete coverage for the pipl.com API
  • Client is completely configurable
  • Using heimdall http client with exponential backoff & more
  • Minimum criteria detection before submitting a pipl query
  • Search by pipl pointer reference
  • Search for a single person via any of the following:
    • Full Name
    • Full Street Address
    • Email
    • Phone
    • Username or UserID or URL
  • Search all possible people
    • Returns the original full person record
    • Searches all possible persons and gets full details
    • Combines all persons into one single response
  • Thumbnail configuration for person.Images
    • Adds image.ThumbnailURL with the complete url for a live thumbnail
  • Test and example coverage for all methods

Examples & Tests

All unit tests and examples run via Travis CI and uses Go version 1.14.x. View the deployment configuration file.

Run all tests (including integration tests)

$ cd ../go-pipl
$ go test ./... -v

Run tests (excluding integration tests)

$ cd ../go-pipl
$ go test ./... -v -test.short

Benchmarks

Run the Go benchmarks:

$ cd ../go-pipl
$ go test -bench . -benchmem

Code Standards

Read more about this Go project's code standards.

Usage

Basic implementation:

package main

import (
	"fmt"
	"log"
	"os"
	"github.com/mrz1836/go-pipl"
)

func main() {

    // Create a client with your api key
    client, _ := pipl.NewClient("your-api-key", nil)

    // Create a new person for searching
    person := pipl.NewPerson()
    person.AddUsername("jeffbezos", "twitter")

    // Submit the search
    response, _ := client.Search(person)

    // Use the pipl response
    fmt.Println(response.Person.Names[0].Display)
    // Output: Jeff Preston Bezos
}

Maintainers

@MrZ

Contributing

This project was based off the original code go pipl project by xpcmdshell

View the contributing guidelines and follow the code of conduct.

Support the development of this project 🙏

Donate

License

License

Documentation

Overview

Package pipl provides a way to interact programmatically with the Pipl API in Golang. For more detailed information on the Pipl search API and what we're actually wrapping, check out their official API reference: https://docs.pipl.com/reference/#overview

Index

Examples

Constants

View Source 
const (

	// ShowSourcesNone specifies that we don't need source info back with search results
	ShowSourcesNone SourceLevel = "false"

	// ShowSourcesAll specifies that we want all source info back with our search results
	ShowSourcesAll SourceLevel = "all"

	// ShowSourcesMatching specifies that we want source info that corresponds to data that satisfies our match requirements
	ShowSourcesMatching SourceLevel = "true"

	// MatchRequirementsNone specifies that we don't have any match requirements for this search
	MatchRequirementsNone MatchRequirements = ""

	// MatchRequirementsEmail specifies that we want to match on this field
	MatchRequirementsEmail MatchRequirements = "email"

	// MatchRequirementsPhone specifies that we want to match on this field
	MatchRequirementsPhone MatchRequirements = "phone"

	// MatchRequirementsEmailAndPhone specifies that we want to match on this field
	MatchRequirementsEmailAndPhone MatchRequirements = "email and phone"

	// MatchRequirementsEmailAndName specifies that we want to match on this field
	MatchRequirementsEmailAndName MatchRequirements = "email and name"

	// MatchRequirementsEmailOrPhone specifies that we want to match on this field
	MatchRequirementsEmailOrPhone MatchRequirements = "email or phone"

	// MinimumProbability is the score for probability
	MinimumProbability = 0.9

	// MinimumMatch is the minimum for a match
	MinimumMatch = 0.0

	// SourceCategoryRequirementsNone specifies that we don't require any specific sources in our results.
	SourceCategoryRequirementsNone SourceCategoryRequirements = ""

	// SourceCategoryRequirementsProfessionalAndBusiness is used for: match_requirements=(emails and jobs)
	SourceCategoryRequirementsProfessionalAndBusiness SourceCategoryRequirements = "professional_and_business"

	// ThumbnailHeight is the default height
	ThumbnailHeight int = 250

	// ThumbnailWidth is the default width
	ThumbnailWidth int = 250

	// DefaultCountry is the default country for address
	DefaultCountry string = "US"

	// DefaultLanguage is the default language
	DefaultLanguage string = "en"

	// DefaultDisplayLanguage is the default display language
	DefaultDisplayLanguage string = "en_US"
)

Package global constants and configuration

Variables

View Source 
var AllowedEthnicities = []string{
	"alaska_native",
	"american_indian",
	"black",
	"chamorro",
	"chinese",
	"filipino",
	"guamanian",
	"japanese",
	"korean",
	"native_hawaiian",
	"other",
	"other_asian",
	"other_pacific_islander",
	"samoan",
	"vietnamese",
	"white",
}

AllowedEthnicities is all the types

Source: https://docs.pipl.com/reference#ethinicity

Note: all lowercase, case sensitive

View Source 
var AllowedServiceProviders = []string{
	"aboutme",
	"badoo",
	"bebo",
	"classmates",
	"cpf",
	"cyworld",
	"delicious",
	"deviantart",
	"digg",
	"douban",
	"ebay",
	"facebook",
	"flavorsme",
	"flickr",
	"flixster",
	"foursquare",
	"freelancer",
	"friendster",
	"gaia",
	"github",
	"goodreads",
	"google",
	"gravatar",
	"habbo",
	"hi5",
	"hyves",
	"imgur",
	"instagram",
	"lastfm",
	"linkedin",
	"livejournal",
	"meetup",
	"myheritage",
	"mylife",
	"myspace",
	"myyearbook",
	"netlog",
	"ning",
	"odnoklassniki",
	"orkut",
	"pinterest",
	"quora",
	"qzone",
	"renren",
	"sonico",
	"soundcloud",
	"stumbleupon",
	"tagged",
	"tumblr",
	"twitter",
	"viadeo",
	"vkontakte",
	"weeworld",
	"xanga",
	"xing",
	"yelp",
	"youtube",
}

AllowedServiceProviders is all the providers

Source: https://docs.pipl.com/reference#section-list-of-known-services

Note: all lowercase, case sensitive

Functions

func SearchMeetsMinimumCriteria added in v0.1.1 

func SearchMeetsMinimumCriteria(searchPerson *Person) bool

SearchMeetsMinimumCriteria is used internally by Search to do some very basic verification that the verify that search object has enough terms to meet the requirements for a search. From Pipl documentation: 

"The minimal requirement to run a search is to have at least one full
name, email, phone, username, user_id, URL or a single valid US address
(down to a house number). We can’t search for a job title or location
alone. We’re not a directory and can't provide bulk lists of people,
rather we specialize in identity resolution of single individuals."
Example

ExampleSearchMeetsMinimumCriteria example using SearchMeetsMinimumCriteria() 

person := new(Person)
if SearchMeetsMinimumCriteria(person) {
	fmt.Println("search meets minimum criteria")
} else {
	fmt.Println("search does not meet minimum criteria")
}

Output:

search does not meet minimum criteria

Types

type Address 

type Address struct {
	Apartment  string `json:"apartment,omitempty"`
	City       string `json:"city,omitempty"`
	Country    string `json:"country,omitempty"`
	Current    bool   `json:"@current,omitempty"`
	Display    string `json:"display,omitempty"`
	House      string `json:"house,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	POBox      string `json:"po_box,omitempty"`
	Raw        string `json:"raw,omitempty"`
	State      string `json:"state,omitempty"`
	Street     string `json:"street,omitempty"`
	Type       string `json:"@type,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
	ZipCode    string `json:"zip_code,omitempty"`
}

Address fields collectively define a possible address for a given person If a search did not return information for a given field, it will be empty.

Source: https://docs.pipl.com/reference#address

type AvailableData 

type AvailableData struct {
	Basic   FieldCount `json:"basic"`
	Premium FieldCount `json:"premium"`
}

AvailableData aggregates the counts for found attributes that are relevant to your search, divided into free and paid sources.

Source: https://docs.pipl.com/reference#available-data

type Client 

type Client struct {
	LastRequest *LastRequest // is the raw information from the last request
	Parameters  *Parameters  // contains application specific values
	// contains filtered or unexported fields
}

Client is the parent struct that wraps the heimdall client

func NewClient 

func NewClient(apiKey string, clientOptions *Options) (c *Client, err error)

NewClient creates a new search client to submit queries with Parameters values are set to the defaults defined by Pipl.

For more information: https://docs.pipl.com/reference#configuration-parameters

Example

ExampleNewClient example using NewClient() 

client, _ := NewClient("1234567890", nil)
fmt.Println(client.Parameters.Search.apiKey)

Output:

1234567890

func (*Client) PiplRequest added in v0.1.4 

func (c *Client) PiplRequest(endpoint string, method string, params *url.Values) (response *Response, err error)

PiplRequest is a generic pipl request wrapper that can be used without the constraints of the Search or SearchByPointer methods

func (*Client) Search added in v0.1.4 

func (c *Client) Search(searchPerson *Person) (response *Response, err error)

Search takes a person object (filled with search terms) and returns the results in the form of a Response struct. If successful, the response struct will contains the results, and err will be nil. If an error occurs, the struct pointer will be nil and you should check err for additional information. This method will only return one full person, and a preview of possible people if < 100% match. Use the SearchAllPossiblePeople() method to get all the details when searching.

func (*Client) SearchAllPossiblePeople added in v0.1.4 

func (c *Client) SearchAllPossiblePeople(searchPerson *Person) (response *Response, err error)

SearchAllPossiblePeople takes a person object (filled with search terms) and returns the results in the form of a Response struct. If possible people are found, they are also looked up using the SearchByPointer()

func (*Client) SearchByPointer 

func (c *Client) SearchByPointer(searchPointer string) (response *Response, err error)

SearchByPointer takes a search pointer string and returns the full information for the person associated with that pointer

type DateOfBirth 

type DateOfBirth struct {
	Current    bool      `json:"@current,omitempty"`
	DateRange  DateRange `json:"date_range,omitempty"`
	Display    string    `json:"display,omitempty"`
	Inferred   bool      `json:"@inferred,omitempty"`
	LastSeen   string    `json:"@last_seen,omitempty"`
	ValidSince string    `json:"@valid_since,omitempty"`
}

DateOfBirth specifies a possible DOB for a person.

Source: https://docs.pipl.com/reference#date-of-birth

type DateRange 

type DateRange struct {
	Current    bool   `json:"@current,omitempty"`
	End        string `json:"end,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	Start      string `json:"start,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
}

DateRange specifies a range of time by a start and end date

Source: https://docs.pipl.com/reference#date-range

type Education 

type Education struct {
	Current    bool      `json:"@current,omitempty"`
	DateRange  DateRange `json:"date_range,omitempty"`
	Degree     string    `json:"degree,omitempty"`
	Display    string    `json:"display,omitempty"`
	Inferred   bool      `json:"@inferred,omitempty"`
	LastSeen   string    `json:"@last_seen,omitempty"`
	School     string    `json:"school,omitempty"`
	ValidSince string    `json:"@valid_since,omitempty"`
}

Education specifies a possible

Source: https://docs.pipl.com/reference#education

type Email 

type Email struct {
	Address       string `json:"address,omitempty"`
	AddressMD5    string `json:"address_md5,omitempty"`
	Current       bool   `json:"@current,omitempty"`
	Disposable    bool   `json:"@disposable,omitempty"`
	EmailProvider bool   `json:"@email_provider,omitempty"`
	Inferred      bool   `json:"@inferred,omitempty"`
	LastSeen      string `json:"@last_seen,omitempty"`
	Type          string `json:"@type,omitempty"`
	ValidSince    string `json:"@valid_since,omitempty"`
}

Email fields collectively define a possible email address for a given person If a search did not return information for a given field, it will be empty.

Source: https://docs.pipl.com/reference#email

type Ethnicity 

type Ethnicity struct {
	Content    string `json:"content,omitempty"`
	Current    bool   `json:"@current,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
}

Ethnicity contains a possible ethnicity of given person.

Source: https://docs.pipl.com/reference#ethinicity

type FieldCount 

type FieldCount struct {
	Addresses       int `json:"addresses"`
	DOBs            int `json:"dobs"`
	Educations      int `json:"educations"`
	Emails          int `json:"emails"`
	Ethnicities     int `json:"ethnicities"`
	Genders         int `json:"genders"`
	Images          int `json:"images"`
	Jobs            int `json:"jobs"`
	LandlinePhones  int `json:"landline_phones"`
	Languages       int `json:"languages"`
	MobilePhones    int `json:"mobile_phones"`
	Names           int `json:"names"`
	OriginCountries int `json:"origin_countries"`
	Phones          int `json:"phones"`
	Relationships   int `json:"relationships"`
	SocialProfiles  int `json:"social_profiles"`
	UserIDs         int `json:"user_ids"`
	Usernames       int `json:"usernames"`
}

FieldCount contains the count of various attributes returned from a search

Source: https://docs.pipl.com/reference#overview-2

type GUID 

type GUID string

GUID is a unique format (but is just a string internally, since there's currently nothing all that fancy done with GUIDs). Additional guid-handling code may be added at a later date if needed.

type Gender 

type Gender struct {
	Content    string `json:"content,omitempty"`
	Current    bool   `json:"@current,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
}

Gender contains a possible gender of the given person. Gender is one of: "male", "female" (There is no default value for this field)

Source: https://docs.pipl.com/reference#gender

type Image 

type Image struct {
	Current        bool   `json:"@current,omitempty"`
	Inferred       bool   `json:"@inferred,omitempty"`
	LastSeen       string `json:"@last_seen,omitempty"`
	ThumbnailToken string `json:"thumbnail_token,omitempty"`
	ThumbnailURL   string `json:"thumbnail_url,omitempty"`
	URL            string `json:"url,omitempty"`
	ValidSince     string `json:"@valid_since,omitempty"`
}

Image specifies a link to an image closely associated with the given person.

Source: https://docs.pipl.com/reference#image

type Job 

type Job struct {
	Current      bool      `json:"@current,omitempty"`
	DateRange    DateRange `json:"date_range,omitempty"`
	Display      string    `json:"display,omitempty"`
	Industry     string    `json:"industry,omitempty"`
	Inferred     bool      `json:"@inferred,omitempty"`
	LastSeen     string    `json:"@last_seen,omitempty"`
	Organization string    `json:"organization,omitempty"`
	Title        string    `json:"title,omitempty"`
	ValidSince   string    `json:"@valid_since,omitempty"`
}

Job specifies information about a possible occupation held by the given person.

Source: https://docs.pipl.com/reference#job

type Language 

type Language struct {
	Current    bool   `json:"@current,omitempty"`
	Display    string `json:"display,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	Language   string `json:"language,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	Region     string `json:"region,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
}

Language contains information about a possible language known by the given person.

Source: https://docs.pipl.com/reference#language

type LastRequest added in v0.1.10 

type LastRequest struct {
	Method     string `json:"method"`      // method is the HTTP method used
	PostData   string `json:"post_data"`   // postData is the post data submitted if POST/PUT request
	StatusCode int    `json:"status_code"` // statusCode is the last code from the request
	URL        string `json:"url"`         // url is the url used for the request
}

LastRequest is used to track what was submitted via the Request()

type MatchRequirements 

type MatchRequirements string

MatchRequirements specifies the conditions for a successful person match in our search. This is useful for saving money with the Pipl API, as you only need to pay for the data you wanted back. If your search results didn't satisfy the match requirements, then no data is returned and you don't pay.

type Name 

type Name struct {
	Current    bool   `json:"@current,omitempty"`
	Display    string `json:"display,omitempty"`
	First      string `json:"first,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	Last       string `json:"last,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	Middle     string `json:"middle,omitempty"`
	Prefix     string `json:"prefix,omitempty"`
	Raw        string `json:"raw,omitempty"`
	Suffix     string `json:"suffix,omitempty"`
	Type       string `json:"@type,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
}

Name fields collectively define a possible name for a given person. If a search did not return information for a given field, it will be empty.

Source: https://docs.pipl.com/reference#name

type Options added in v0.2.0 

type Options struct {
	BackOffExponentFactor          float64       `json:"back_off_exponent_factor"`
	BackOffInitialTimeout          time.Duration `json:"back_off_initial_timeout"`
	BackOffMaximumJitterInterval   time.Duration `json:"back_off_maximum_jitter_interval"`
	BackOffMaxTimeout              time.Duration `json:"back_off_max_timeout"`
	DialerKeepAlive                time.Duration `json:"dialer_keep_alive"`
	DialerTimeout                  time.Duration `json:"dialer_timeout"`
	RequestRetryCount              int           `json:"request_retry_count"`
	RequestTimeout                 time.Duration `json:"request_timeout"`
	TransportExpectContinueTimeout time.Duration `json:"transport_expect_continue_timeout"`
	TransportIdleTimeout           time.Duration `json:"transport_idle_timeout"`
	TransportMaxIdleConnections    int           `json:"transport_max_idle_connections"`
	TransportTLSHandshakeTimeout   time.Duration `json:"transport_tls_handshake_timeout"`
	UserAgent                      string        `json:"user_agent"`
}

Options holds all the configuration for connection, dialer and transport

func ClientDefaultOptions added in v0.2.0 

func ClientDefaultOptions() (clientOptions *Options)

ClientDefaultOptions will return an Options struct with the default settings Useful for starting with the default and then modifying as needed

type OriginCountry 

type OriginCountry struct {
	Country    string `json:"country,omitempty"`
	Current    bool   `json:"@current,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
}

OriginCountry contains information about a possible origin country of the given person.

Source: https://docs.pipl.com/reference#origin-country

type Parameters added in v0.2.0 

type Parameters struct {
	Search    *SearchParameters  // contains the search parameters that are submitted with your query, which may affect the data returned
	Thumbnail *ThumbnailSettings // is for the thumbnail url settings
	UserAgent string             // (optional for changing user agents)
}

Parameters are application specific values for requests

type Person 

type Person struct {
	Addresses       []Address       `json:"addresses,omitempty"`
	DateOfBirth     *DateOfBirth    `json:"dob,omitempty"`
	Educations      []Education     `json:"educations,omitempty"`
	Emails          []Email         `json:"emails,omitempty"`
	Ethnicities     []Ethnicity     `json:"ethnicities,omitempty"`
	Gender          *Gender         `json:"gender,omitempty"`
	ID              GUID            `json:"@id,omitempty"`
	Images          []Image         `json:"images,omitempty"`
	Inferred        bool            `json:"@inferred,omitempty"`
	Jobs            []Job           `json:"jobs,omitempty"`
	Languages       []Language      `json:"languages,omitempty"`
	Match           float32         `json:"@match,omitempty"`
	Names           []Name          `json:"names,omitempty"`
	OriginCountries []OriginCountry `json:"origin_countries,omitempty"`
	Phones          []Phone         `json:"phones,omitempty"`
	Relationships   []Relationship  `json:"relationships,omitempty"`
	SearchPointer   string          `json:"@search_pointer,omitempty"`
	URLs            []URL           `json:"urls,omitempty"`
	UserIDs         []UserID        `json:"user_ids,omitempty"`
	Usernames       []Username      `json:"usernames,omitempty"`
}

Person contains all the information pertaining to a possible person match, including potential multiples of basic fields (names, emails, jobs, etc). The Match field represents the confidence of a particular person match, as a float: 0 <= Match <= 1. More potential matches returned in a search decreases the overall confidence of all matches.

Source: https://docs.pipl.com/reference#person

func NewPerson 

func NewPerson() *Person

NewPerson makes a new blank person object to be filled with terms

func (*Person) AddAddress 

func (p *Person) AddAddress(house, street, apartment, city, state, country, poBox string) (err error)

AddAddress appends an address to the specified search object

Source: https://docs.pipl.com/reference#address

Note: Values are assumed to be sanitized/validated already

Plan: All Plans

Example

ExamplePerson_AddAddress example using AddAddress() 

person := NewPerson()
_ = person.AddAddress("10", "Hickory Lane", "1", "Smallville", "KS", DefaultCountry, "123")
fmt.Println(person.Addresses[0].House + " " + person.Addresses[0].Street + ", " + person.Addresses[0].City + " " + person.Addresses[0].State)

Output:

10 Hickory Lane, Smallville KS

func (*Person) AddAddressRaw 

func (p *Person) AddAddressRaw(fullAddress string) (err error)

AddAddressRaw can be used when many of the address parts are missing, or you're unsure how to split it up. Let Pipl handle parsing.

Source: https://docs.pipl.com/reference#address

Note: Values are assumed to be sanitized/validated already

Plan: All Plans

Example

ExamplePerson_AddAddressRaw example using AddAddressRaw() 

person := NewPerson()
_ = person.AddAddressRaw("10 Hickory Lane, Kansas, " + DefaultCountry)
fmt.Println(person.Addresses[0].Raw)

Output:

10 Hickory Lane, Kansas, US

func (*Person) AddEducation 

func (p *Person) AddEducation(degree, school, dateRangeStart, dateRangeEnd string) (err error)

AddEducation appends an education entry to the specified search object

Source: https://docs.pipl.com/reference#education

Note: Values are assumed to be sanitized/validated already

Plan: Business Plan

Example

ExamplePerson_AddEducation example using AddEducation() 

person := NewPerson()
_ = person.AddEducation("masters", "fau", "2010-01-01", "2011-01-01")
fmt.Println(person.Educations[0].Degree + " from " + person.Educations[0].School)

Output:

masters from fau

func (*Person) AddEmail 

func (p *Person) AddEmail(emailAddress string) (err error)

AddEmail appends an email address to the specified search object

Source: https://docs.pipl.com/reference#email

Note: Values are assumed to be sanitized/validated already

Plan: Business Plan

Example

ExamplePerson_AddEmail example using AddEmail() 

person := NewPerson()
_ = person.AddEmail("clarkkent@gmail.com")
fmt.Println(person.Emails[0].Address)

Output:

clarkkent@gmail.com

func (*Person) AddEthnicity 

func (p *Person) AddEthnicity(ethnicity string) (err error)

AddEthnicity appends an ethnicity to the specified search object Ethnicity data is not yet available. (6/8/19)

Source: https://docs.pipl.com/reference#ethinicity

Note: Values are assumed to be sanitized/validated already

Plan: All Plans

Example

ExamplePerson_AddEthnicity example using AddEthnicity() 

person := NewPerson()
_ = person.AddEthnicity("white")
fmt.Println(person.Ethnicities[0].Content)

Output:

white

func (*Person) AddJob 

func (p *Person) AddJob(title, organization, industry, dateRangeStart, dateRangeEnd string) (err error)

AddJob appends a job entry to the specified search object

Source: https://docs.pipl.com/reference#job

Note: Values are assumed to be sanitized/validated already

Plan: Business Plan

Example

ExamplePerson_AddJob example using AddJob() 

person := NewPerson()
_ = person.AddJob("reporter", "daily post", "news", "2010-01-01", "2011-01-01")
fmt.Println(person.Jobs[0].Title + " at " + person.Jobs[0].Organization + " in " + person.Jobs[0].Industry)

Output:

reporter at daily post in news

func (*Person) AddLanguage 

func (p *Person) AddLanguage(languageCode, regionCode string) (err error)

AddLanguage appends a language to the specified search object. Language is a 2 character language code (e.g. "en") Region is a country code (e.g "US") Alpha-2 ISO 3166 country code Language objects are not used by the API for search.

Source: https://docs.pipl.com/reference#language

Note: Values are assumed to be sanitized/validated already

Plan: All Plans

Example

ExamplePerson_AddLanguage example using AddLanguage() 

person := NewPerson()
_ = person.AddLanguage(DefaultLanguage, DefaultCountry)
fmt.Println(person.Languages[0].Display)

Output:

en_US

func (*Person) AddName 

func (p *Person) AddName(firstName, middleName, lastName, prefix, suffix string) (err error)

AddName adds a name to the search object. For well defined names.

Source: https://docs.pipl.com/reference#name

Note: Values are assumed to be sanitized already

Plan: All Plans

Example

ExamplePerson_AddName example using AddName() 

person := NewPerson()
_ = person.AddName("clark", "ryan", "kent", "mr", "jr")
fmt.Println(person.Names[0].First + " " + person.Names[0].Last)

Output:

clark kent

func (*Person) AddNameRaw 

func (p *Person) AddNameRaw(fullName string) (err error)

AddNameRaw can be used when you're unsure how to handle breaking down the name in question into its constituent parts. Basically, let Pipl handle parsing it.

Source: https://docs.pipl.com/reference#name

Note: Values are assumed to be sanitized already

Plan: All Plans

Example

ExamplePerson_AddNameRaw example using AddNameRaw() 

person := NewPerson()
_ = person.AddNameRaw("clark kent")
fmt.Println(person.Names[0].Raw)

Output:

clark kent

func (*Person) AddOriginCountry 

func (p *Person) AddOriginCountry(countryCode string) (err error)

AddOriginCountry appends an origin country to the specified search object Alpha-2 ISO 3166 country code

Source: https://docs.pipl.com/reference#origin-country

Note: Values are assumed to be sanitized/validated already

Plan: All Plans

Example

ExamplePerson_AddOriginCountry example using AddOriginCountry() 

person := NewPerson()
_ = person.AddOriginCountry(DefaultCountry)
fmt.Println(person.OriginCountries[0].Country)

Output:

US

func (*Person) AddPhone 

func (p *Person) AddPhone(phoneNumber, countryCode int) (err error)

AddPhone appends a phone to the specified search object

Source: https://docs.pipl.com/reference#phone

Note: Values are assumed to be sanitized/validated already

Plan: Landline phones are available in all plans, mobile phones 

in the BUSINESS plan only.
Example

ExamplePerson_AddPhone example using AddPhone() 

person := NewPerson()
_ = person.AddPhone(9785550145, 1)
fmt.Println(person.Phones[0].Number)

Output:

9785550145

func (*Person) AddPhoneRaw added in v0.1.1 

func (p *Person) AddPhoneRaw(phoneNumber string) (err error)

AddPhoneRaw appends a phone to the specified search object

Source:https://docs.pipl.com/reference#phone

Note: Values are assumed to be sanitized/validated already

Plan: Landline phones are available in all plans, mobile phones 

in the BUSINESS plan only.
Example

ExamplePerson_AddPhoneRaw example using AddPhoneRaw() 

person := NewPerson()
_ = person.AddPhoneRaw("9785550145")
fmt.Println(person.Phones[0].Raw)

Output:

9785550145

func (*Person) AddRelationship 

func (p *Person) AddRelationship(relationship Relationship) (err error)

AddRelationship appends a relationship entry to the specified search object

Source: https://docs.pipl.com/reference#relationship

Note: Values are assumed to be sanitized/validated already

Plan: Social Plan

func (*Person) AddURL 

func (p *Person) AddURL(url string) (err error)

AddURL appends a URL to the specified search object (website, social, etc)

Source: https://docs.pipl.com/reference#url

Note: Values are assumed to be sanitized/validated already

Plan: Social Plan

Example

ExamplePerson_AddURL example using AddURL() 

person := NewPerson()
_ = person.AddURL("https://twitter.com/clarkkent")
fmt.Println(person.URLs[0].URL)

Output:

https://twitter.com/clarkkent

func (*Person) AddUserID 

func (p *Person) AddUserID(userID, serviceProvider string) (err error)

AddUserID appends a user ID to the specified search object

Source: https://docs.pipl.com/reference#user-id

Note: Values are assumed to be sanitized/validated already

Plan: Social Plan

Example

ExamplePerson_AddUserID example using AddUserID() 

person := NewPerson()
_ = person.AddUserID("clarkkent", "twitter")
fmt.Println(person.UserIDs[0].Content)

Output:

clarkkent@twitter

func (*Person) AddUsername 

func (p *Person) AddUsername(username string, serviceProvider string) (err error)

AddUsername appends a username to the specified search object

Source: https://docs.pipl.com/reference#username

Note: Values are assumed to be sanitized/validated already

Plan: Social Plan

Example

ExamplePerson_AddUsername example using AddUsername() 

person := NewPerson()
_ = person.AddUsername("clarkkent", "twitter")
fmt.Println(person.Usernames[0].Content)

Output:

clarkkent@twitter

func (*Person) HasAddress added in v0.1.1 

func (p *Person) HasAddress() bool

HasAddress returns true if the person has an address (minimum required)

func (*Person) HasEmail added in v0.1.1 

func (p *Person) HasEmail() bool

HasEmail returns true if the person has an email address

func (*Person) HasName added in v0.1.1 

func (p *Person) HasName() bool

HasName returns true if the person has a name (minimum required)

func (*Person) HasPhone added in v0.1.1 

func (p *Person) HasPhone() bool

HasPhone returns true if the person has a phone number

func (*Person) HasURL added in v0.1.1 

func (p *Person) HasURL() bool

HasURL returns true if the person has a url

func (*Person) HasUserID added in v0.1.1 

func (p *Person) HasUserID() bool

HasUserID returns true if the person has a user id

func (*Person) HasUsername added in v0.1.1 

func (p *Person) HasUsername() bool

HasUsername returns true if the person has a username

func (*Person) ProcessThumbnails added in v0.1.3 

func (p *Person) ProcessThumbnails(c *Client)

ProcessThumbnails checks for any images and adds thumbnail urls to the existing image Requires the client for now since the client has the current configuration

Example

ExamplePerson_ProcessThumbnails example using ProcessThumbnails() 

client, _ := NewClient("1234567890", nil)
person := NewPerson()

image := new(Image)
image.URL = testImage
image.ThumbnailToken = testThumbnailToken
person.Images = append(person.Images, *image)

person.ProcessThumbnails(client)
fmt.Println(person.Images[0].ThumbnailURL)

Output:

https://thumb.pipl.com/image?height=250&width=250&favicon=false&zoom_face=false&tokens=AE2861B242686E7BD0CB4D9049298EB7D18FEF66D950E8AB78BCD3F484345CE74536C19A85D0BA3D32DC9E7D1878CD4D341254E7AD129255C6983E6E154C4530A0DAAF665EA325FC0206F8B1D7E0B6B7AD9EBF71FCF610D57D

func (*Person) SetDateOfBirth 

func (p *Person) SetDateOfBirth(startDate, endDate string) (err error)

SetDateOfBirth sets the DOB of the specified search object DOB string format: "YYYY-MM-DD" Set both Start and End to the same date if known

Source: https://docs.pipl.com/reference#date-of-birth

Note: Values are assumed to be sanitized/validated already

Plan: All Plans

Example

ExamplePerson_SetDateOfBirth example using SetDateOfBirth() 

person := NewPerson()
_ = person.SetDateOfBirth("1987-01-01", "1987-01-01")
fmt.Println(person.DateOfBirth.DateRange.Start)

Output:

1987-01-01

func (*Person) SetGender 

func (p *Person) SetGender(gender string) (err error)

SetGender sets the gender of the specified search object

Source: https://docs.pipl.com/reference#gender

Note: Values are assumed to be sanitized/validated already

Plan: All Plans

Example

ExamplePerson_SetGender example using SetGender() 

person := NewPerson()
_ = person.SetGender("male")
fmt.Println(person.Gender.Content)

Output:

male

type Phone 

type Phone struct {
	CountryCode          int    `json:"country_code,omitempty"`
	Current              bool   `json:"@current,omitempty"`
	Display              string `json:"display,omitempty"`
	DisplayInternational string `json:"display_international,omitempty"`
	Extension            int    `json:"extension,omitempty"`
	Inferred             bool   `json:"@inferred,omitempty"`
	LastSeen             string `json:"@last_seen,omitempty"`
	Number               int    `json:"number,omitempty"`
	Raw                  string `json:"raw,omitempty"`
	Type                 string `json:"@type,omitempty"`
	ValidSince           string `json:"@valid_since,omitempty"`
}

Phone fields collectively define a possible phone number for a given person If a search did not return information for a given field, it will be empty.

Source: https://docs.pipl.com/reference#phone

type Relationship 

type Relationship struct {
	Addresses       []Address       `json:"addresses,omitempty"`
	Current         bool            `json:"@current,omitempty"`
	DateOfBirth     DateOfBirth     `json:"dob,omitempty"`
	Educations      []Education     `json:"educations,omitempty"`
	Emails          []Email         `json:"emails,omitempty"`
	Ethnicities     []Ethnicity     `json:"ethnicities,omitempty"`
	Gender          Gender          `json:"gender,omitempty"`
	Images          []Image         `json:"images,omitempty"`
	Inferred        bool            `json:"@inferred,omitempty"`
	Jobs            []Job           `json:"jobs,omitempty"`
	Languages       []Language      `json:"languages,omitempty"`
	LastSeen        string          `json:"@last_seen,omitempty"`
	Names           []Name          `json:"names,omitempty"`
	OriginCountries []OriginCountry `json:"origin_countries,omitempty"`
	Phones          []Phone         `json:"phones,omitempty"`
	Relationships   []Relationship  `json:"relationships,omitempty"`
	Subtype         string          `json:"@subtype,omitempty"`
	Type            string          `json:"@type,omitempty"`
	UserIDs         []UserID        `json:"user_ids,omitempty"`
	Usernames       []Username      `json:"usernames,omitempty"`
	ValidSince      string          `json:"@valid_since,omitempty"`
}

Relationship contains information about a person who is closely related to the person being searched. This can be family members, spouses, children, etc. Type and Subtype contain information about the nature of the relationship to the person being searched. For example, Type = "Family", Subtype = "Father". Type can be one of: "work", "family", "friend" (default), "other"

Source: https://docs.pipl.com/reference#relationship

type Response 

type Response struct {
	AvailableData     AvailableData `json:"available_data"`
	AvailableSources  int           `json:"@available_sources"`
	Error             string        `json:"error"`
	HTTPStatusCode    int           `json:"@http_status_code"`
	MatchRequirements string        `json:"match_requirements"`
	Person            Person        `json:"person"`
	PersonsCount      int           `json:"@persons_count"`
	PossiblePersons   []Person      `json:"possible_persons"`
	Query             Person        `json:"query"`
	SearchID          string        `json:"@search_id"`
	Sources           []Source      `json:"sources"`
	VisibleSources    int           `json:"@visible_sources"`
	Warnings          []string      `json:"warnings"`
}

Response holds search results and general request information returned from the Pipl API. If an error occurs, the Error field will have more information. A search may be successful, but have some warnings. These are held in the Warnings field.

Source: https://docs.pipl.com/reference#overview-2

type SearchParameters 

type SearchParameters struct {

	// MinimumProbability is the minimum acceptable probability for inferred data
	MinimumProbability float32

	// InferPersons specifies whether or not the Pipl should return results inferred by statistical analysis
	InferPersons bool

	// MinimumMatch specifies the minimum match confidence for a possible person to be returned in search results
	MinimumMatch float32

	// ShowSources specifies the level of sources info to return with search results, one of {ShowSourcesMatching, ShowSourcesAll, ShowSourcesNone}
	ShowSources SourceLevel

	// HideSponsored specifies whether to omit sponsored data from search results
	HideSponsored bool

	// LiveFeeds specifies whether to use live data sources
	LiveFeeds bool

	// MatchRequirements specifies the criteria for a successful Person match.
	// Results that don't fit your match requirements are discarded. If the remaining
	// search results would be empty, you are not charged for the query.
	MatchRequirements MatchRequirements

	// SourceCategoryRequirements specifies the data categories that must be included in
	// results for a successful match. If there is no data from the requested categories,
	// then the results returned are empty and you're not charged.
	SourceCategoryRequirements SourceCategoryRequirements
	// contains filtered or unexported fields
}

SearchParameters holds options that can affect data returned by a search.

Source: https://docs.pipl.com/reference#configuration-parameters

type Source 

type Source struct {
	Addresses       []Address       `json:"addresses"`
	Category        string          `json:"@category"`
	DateOfBirth     DateOfBirth     `json:"dob"`
	Domain          string          `json:"@domain"`
	Educations      []Education     `json:"educations"`
	Emails          []Email         `json:"emails"`
	Ethnicities     []Ethnicity     `json:"ethnicities"`
	Gender          Gender          `json:"gender"`
	ID              string          `json:"@id"`
	Jobs            []Job           `json:"jobs"`
	Languages       []Language      `json:"languages"`
	Match           float32         `json:"@match"`
	Name            string          `json:"@name"`
	Names           []Name          `json:"names"`
	OriginCountries []OriginCountry `json:"origin_countries"`
	OriginURL       string          `json:"@origin_url"`
	PersonID        GUID            `json:"@person_id"`
	Phones          []Phone         `json:"phones"`
	Premium         bool            `json:"@premium"`
	Relationships   []Relationship  `json:"relationships"`
	Sponsored       bool            `json:"@sponsored"`
	Tags            []Tag           `json:"tags"`
	URLs            []URL           `json:"urls"`
	UserIDs         []UserID        `json:"user_ids"`
	Usernames       []Username      `json:"usernames"`
}

Source contains all the information for a given person, gathered from a single source. The source structure contains information about the name, domain, category, and source URL (amongst other fields).

Source: https://docs.pipl.com/reference#source

type SourceCategoryRequirements 

type SourceCategoryRequirements string

SourceCategoryRequirements specifies the data categories that must be included in results for a successful match. If there is no data from the requested categories, then the results returned are empty and you're not charged.

type SourceLevel 

type SourceLevel string

SourceLevel is used internally to represent the possible values for show_sources in queries to be submitted: {"all", "matching"/"true", "false"}

type Tag 

type Tag struct {
	Classification string `json:"@classification,omitempty"`
	Content        string `json:"content,omitempty"`
}

Tag contains content classification information

Source: https://docs.pipl.com/reference#tag

type ThumbnailSettings added in v0.1.3 

type ThumbnailSettings struct {
	// Enabled (detects images, automatically adds thumbnail urls)
	Enabled bool

	// URL is the thumbnail url
	URL string

	// Height of the image
	Height int

	// Width of the image
	Width int

	// Favicon if the icon should be shown or not
	Favicon bool

	// ZoomFace is whether to enable face zoom.
	ZoomFace bool
}

ThumbnailSettings is for the thumbnail url settings to be automatically returned if any images are found and meet the criteria

Example: http://thumb.pipl.com/image?height=250&width=250&favicon=true&zoom_face=true&tokens=FIRST_TOKEN,SECOND_TOKEN

type URL 

type URL struct {
	Category   string `json:"@category,omitempty"`
	Current    bool   `json:"@current,omitempty"`
	Domain     string `json:"@domain,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	Name       string `json:"@name,omitempty"`
	SourceID   string `json:"@source_id,omitempty"`
	URL        string `json:"url,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
}

URL contains information about a URL that is closely associated with a given person.

Source: https://docs.pipl.com/reference#url

type UserID 

type UserID struct {
	Content    string `json:"content,omitempty"`
	Current    bool   `json:"@current,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
}

UserID fields collectively define a possible UserID used by a given person. If a search did not return information for a given field, it will be empty.

Source: https://docs.pipl.com/reference#user-id

type Username 

type Username struct {
	Content    string `json:"content,omitempty"`
	Current    bool   `json:"@current,omitempty"`
	Inferred   bool   `json:"@inferred,omitempty"`
	LastSeen   string `json:"@last_seen,omitempty"`
	ValidSince string `json:"@valid_since,omitempty"`
}

Username fields collectively define a possible username used by a given person. If a search did not return information for a given field, it will be empty.

Source: https://docs.pipl.com/reference#username

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.