API Documentation

Information on Liquid and Grit’s API

Overview

Liquid and Grit has developed a RESTful API and is available to select clients to support their need to directly access our data. As a RESTful API, clients are free to use their programming tool of choice and use standard HTTP features to access the data.

All API calls are made to the following endpoints and all responses will return a JSON object:

• /api/cnd/get - Feature Database

• /api/cnd/event-tracker/get - Events

Authentication

The API requires authentication in order for a request to be served. You will need two items of information to be successfully authenticated:

• client id

• api key

This authentication information should be included in every API request presented to our server.

Please contact your Liquid and Grit representative for details on acquiring the above credentials or email [email protected].

API access is for Enterprise level account holders only.

Querying the Data

The API automates the Features Database query process currently provided by our online tool and accepts only the GET method. Other HTTP methods are not allowed and will result in a client error.

The API requires you to submit all necessary information in one query string. This includes both your credentials and other information needed to complete your data request. The components of this query string are provided below. Please note that some are required while others are optional.

To illustrate use of our API, an example using Python is presented below.

Using Python with the REST API

The Python example uses the requests library to process the request and the json library to read the delivered data.

After importing the necessary libraries, the above example defines your credentials and the endpoint (url). The next step is to construct the complete query string before passing it to the API using the request library. This last step is explained in more detail below.

Define Query String

The query string is passed as a Python dictionary with each component of the string representing key:value pairs. The first three components are your credentials (client-id, api-key) and required ‘id’. The next component is the filter, which defines the parameters used for data selection.

If using the standard requests library, the filter array must be passed one component at a time using index[notation] slicers to specify each part of the filter array as a separate parameter in the query string. For example, to identify the filter parameter ‘page’, you will specify the key:value pair as ‘filter[page]’: @value. For filter parameters accepting a range of values (e.g. date_range_published or date_range_added), you will need to follow the parameter identification with an index of [0] or [1] to identify the start and end date respectively as demonstrated in the example.

API Response

The API will return a JSON object in response to your request. The object will arrive in plain text format and will require the use of the json library to parse the data. In the example, the json.load method is used to read the object text and specifies the ‘results’ key using index notation ([‘results’][0]) to access the first record (displayed below).