API technical information

Authentication using OAuth

OAuth is a frequently used method to access protected resources through Application Programming Interfaces (APIs). OAuth thus allows third party software to access user-data or server resources on behalf of a resource owner without sharing their credentials. For the LI-API this means that OAuth serves a solid basis to have LI-users delegate access to personal LI-resources such that a third party app can, for example, access user alerts or user dossiers. OAuth uses a authorization server and a resource server. The latter containing the resources and is responsible to make them available to properly authenticated and authorized clients. The authorization server is responsible for managing authorization based upon access and refresh tokens.

The API will use “Client Credentials Grant” type for authorization. The client requests an access token using its client credentials. Client credentials are passed to authorization server by using x-www-from-urlencoded method or by basic authentication method.

Example Generating a Token

Using the user email and its secret key, one can generate a token. Below you will find a few steps to generate a token on the https://api.legalintelligence.com/nl/token endpoint.

For starters, the secret key (or client secret) of an LI user can be retrieved with the following URL after the user account which maintains access to the LI API is logged into LI: https://www.legalintelligence.com/nl/userprofile?opengenerateapikeylightbox=true

This requires a POST message to https://api.legalintelligence.com/nl/token using two key-pair in the HEADER and three key-value pairs in the BODY.

1. The HEADER should set the Content-Type to application/x-www-form-urlencoded and the X-SubSiteCode to LI.
2. The BODY should set the grant_type to client_credentials, the client_id should contain your user name and the client_secret should be set to client secret.
3. This generates a temporal token which can be used in other endpoints, e.g. https://api.legalintelligence.com/nl/search.

Example Using the Search Endpoint

Once a token is (re)generated, searching can be done in the following way:

1. Searching is possible by adding the search query behind the q= variable. A search for ‘moord’ looks like https://api.legalintelligence.com/nl/search?q=moord. The method requires a urlencoded GET action and the HEADER should be filled with the key-value pairs Authorization key and the value Bearer + Token.
2. The response yields the search results in json (or XML).

Example Using Filter options (NavigationGroups)

Filtering, known as NavigationGroups in the API, is a powerful option to navigate through the set of results. For example, searching trough all the content is accomplished by the wildcard symbol being the *. In this case, searching on everything is accomplished by the GET request https://api.legalintelligence.com/nl/search?q=* yielding first of all a considerable number of Documents (see the overall count) and secondly a number of NavigationGroups.

When the NavigationGroups are de-collapsed, the different filter options are shown. These filter options are comparable with the filter option in Legal Intelligence. Given the applicable NavigationGroups, if one wants to apply the Nederland/Rechtspraak filter, one needs to extend the search query with the fq parameter, like:

https://api.legalintelligence.com/nl/search?q=*&fq={“i”:4,”f”:”TopLevelNavigation”,”n”:”Nederland|Rechtspraak”,”fn”:”Nederland/Rechtspraak“}  

The available fq options and its format can be retrieved from the fq query. The filter can be directly applied in as the fq parameter. For the filtering on Nederland/Rechtspraak, the filter looks like this:

{“i”:4,”f”:”TopLevelNavigation”,”n”:”Nederland|Rechtspraak”,”fn”:”Nederland/Rechtspraak”}

Applying filters can be applied recursively; so multiple fq’s can be added to the call. So, applying the filter Nederland/Rechtspraak followed by Europeese gerechtshovenlooks like this:

https://api.legalintelligence.com/nl/search?q=*&fq={“i”:4,”f”:”TopLevelNavigation”,”n”:”Nederland|Rechtspraak”,”fn”:”Nederland/Rechtspraak”}&fq={“i”:37387,”f”:”IssuingInstitution_Group”,”n”:”Europese gerechtshoven”,”g”:true}  

Other filters can be applied in a similar fashion. So, applying the 2000-2009 date filter looks like this:

https://api.legalintelligence.com/nl/search?q=*&fq={“f”:”PublicationDateYear_Group”,”n”:”2″,”g”:true,”st”:”QF”,”sf”:”PublicationDate:[20000000 TO 20091231]”}  

The fun part of the date filter is that the PublicationDate can be changed to any way one likes. So if one wishes to filter between beginning of the year 2000 till the beginning of the year 2001, the Publication data should look like [20000000 TO 20010000].

Limitations

There are limits set to how many requests you can send. The limit per second is 15, and per minute 100. If you cross this limit then you will get a 429 response (too many requests).