In one of our recent projects, we had the opportunity to work with the LinkedIn People Search API. Using LinkedIn for signing in is becoming more and more popular these days, but in this project, the Client wanted us write an application which is able to perform people searches.

In this post, we want to share what we learned about the possibilities and limitations of the API for non-technical people that are or may be planning to use the API.

Intended use

The first thing you have to do is make sure that the intended use of application does not violate LinkedIn’s Terms and Conditions. Think over what the application is for, who the target audience is, and whether these are in accordance with the People Search API documentation which states that:

• “It may not be used for the purposes of database matching, candidate sourcing, or lead generation without an established business relationship with LinkedIn. For information on partnership opportunities, and how to apply, visit our Partner Programs page.

• Search results may not be stored or offered as aggregated search.

• All API calls must be made within an active user session.

• You cannot let multiple people search using the authentication credentials of one person. Each person must authenticate individually.”

Only if you feel confident that your application can comply with these terms should development start. We do our best to warn clients of the possibility of having an application banned, but we are not legal experts, and do not take responsibility for developing an application that is determined to be violating T&C.

The second restriction you should be aware of is that People Search API is available only for logged in users, and only within the 1st and 2nd degree connections of the logged in user. It means that the API will search only in the 1st and 2nd degree connections of the user. Searching for “out of network” people that are not either 1st or 2nd degree connections is possible only if the search query includes both the first and last name of the person. So you must exactly know whom you are looking for.

People Search API throttle limits

LinkedIn sets strict throttle limits for Search API calls. Only 100 results will be provided for each search and 10 results will be displayed per page. Displaying each page is considered one API call.

Your application can have 100K calls per day, but individual users will have only 100 calls per day (400 for developers). The counter resets at 24:00 every day. A developer working on the app could easily reach that limit early in the day and not be able to perform another search before midnight.

Though there is an option to buy different Premium Plans which can give you more options as a LinkedIn user, on the official developer forum about the API permission model, it says that “The level of account you have with LinkedIn doesn't affect what you can do as far as API queries go.”” (source)

Development

Without going into too many technological details, we would like to briefly point out some of the benefits of using Ruby on Rails for a project like this.

The fun part about being a Rails developer is when you’re integrating with a service that is basically guaranteed to have some 3rd party library (or gem) that take care of part of your work for you. For the people search API, we used the gem called linkedin (https://github.com/pengwynn/linkedin), and for the LinkedIn sign-in process we chose the omniauth-linkedin gem (https://github.com/skorks/omniauth-linkedin) as an extension for the famous devise user management library.

Using gems like these will ensure that your developers don’t have to reinvent the wheel, and the implemented solution will be constantly tested and upgraded by the open-source community of Ruby developers.

Conclusion

LinkedIn has built a great professional network, and it is natural that they want to protect the greatest value of the site. So if you can accept the limitations and restrictions of the People Search API, it can be a useful additional add-on or feature for your application.

However if you are planning to use the API heavily with use cases that include people search as a main feature, then we would recommend first establishing an agreement with LinkedIn before risking getting your app banned. :)