How to Spot the Right Person with Search Pointers

One of the coolest additions in our latest API release, v4, are the search pointers. They offer a complete solution to one of the most commonly used search patterns – the drill down search.

So how does it work?

Say you’re looking for John Smith from Florida. Naturally, running that kind of search will not get you a definite match of the John Smith you are looking for, since there are many people named John Smith in Florida.

Instead, the API response will contain a list of all the people who match your search criteria – in this case John Smith from Florida.

This is where the cool stuff begins. Each of the possible persons will have a special attribute, “search_pointer” – it will be a long string of seemingly random numbers and letters. In reality, the string is an internal representation of the person, which our servers will be able to use to dig up more information about this person.

Going over the list of possible persons, you can find the person you’re looking for based on different data points – jobs, education, age and so forth. Once you’ve identified the John Smith you’re interested in – use his search pointer to bring up everything we have on him.

Cool, show me how!

Using the search pointers is extremely easy, and is built into all of our client libraries. For the purpose of this tutorial I will use Python examples – but this can be easily done in the other client libraries in much the same fashion.

For the sake of this tutorial, we will simulate a very simple people search engine.

On the first step, an end user will enter some search parameters. In our case, John Smith from Florida. Your piece of code which handles user searches will then make the request to our API:

[python]from piplapis.search import SearchAPIRequest
request = SearchAPIRequest(first_name=u’John’, last_name=u’Smith’, state=u’FL’, country=u’US’)
response = request.send()[/python]

You now have a search response object, which will include a list member – possible_persons. The list will be composed of Person objects. The search pointer can be found under person.search_pointer.

You can now display those people in your UI, and let your end user choose the right person.

Once you know the search pointer of the correct person, you will run another search:

[python]request = SearchAPIRequest(search_pointer=SEARCH_POINTER_STRING)
response = request.send()[/python]

The response object will now contain a full person object, with all the information available about this specific John Smith.

I hope you found this tutorial useful – it outlines a simple and effective way of using search pointers in order to implement a drill down search pattern.

Are you using search pointers differently? Did you run into any issues and need some assistance? Drop us a message at developers@pipl.com.