API Documentation
Information on Liquid and Grit’s API
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 endpoint and all responses will return a JSON object:
https://my.liquidandgrit.com/api/cnd/get
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.
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.
Parameter | Notes |
|---|---|
client_id | First part of your credential set (required) |
api_key | Second part of your credential set (required) |
id | Required value = 1 If no value is passed, no data will be returned. |
tag_group_data | Required value = 1 If a value other than 1 is provided, data may be returned but its accuracy is not assured. |
page | Optional with default set to 0 |
limit | Optional with default set to 200 Both page and limit work together to select a slice of the table data. If you are uncertain as to which slice you wish to select, the best option is to accept the defaults. |
date_range_published or date_range_added | Provided as a date range with only one date range per call: From: YYYY-MM-DD HH:MM:SS To: YYYY-MM-DD HH:MM:SS This parameter restricts data based on published or added date. You may assert either one or both. However, if both are provided, the response will be based on the published date. |
To illustrate use of our API, an example using Python is presented below.
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.
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.
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).