Query parameters
Below is a sample selection of the most commonly used query parameters. The API supports a wide range of query parameters, for the complete list visit the Swagger documentation.
‘q’
The q parameter enables Boolean filtering of the response using combinations of metadata points and text searches. Expressions take the form of field:value pairs separated by spaces and the Boolean terms AND, OR, NOT. Parenthesis () can be used to logically group terms together. A full list of fields available is under [link – Query fields] in the Query Parameters section.
For example, to return ‘Covenants’ clauses that contain the word “responsibility” you can use the following:
The id for the Covenants clause is 1933. You can find a full list of id numbers for a given field by querying the corresponding /referencedata/{field} end point for that field.
To return ‘Covenants’, or ‘Risk Factors’ clauses that contain the word “responsibility” you can use the following:
To return ‘Covenants’ clauses that contain the word “responsibility”, where the issuer is based in the United States, you can use the following query (United States country Id is 2).
The clauseText field is unique in that it enables you enter additional text search Boolean within its value pairing. For example, if you wish to search for clauses that contain either the words ‘Bond’ OR ‘Certificate’, AND the phrase “British Airways” within Covenants then you can use the following:
If the value you need to enter for a clauseText search contains spaces, then it needs to be wrapped in brackets, e.g. clauseText:(Preferred AND Securities). The following table shows examples and explanations of text search syntax.
Single Term | Bond | Searches for a single word |
Phrase | “Preferred Securities” | Searches for a group of words in word order |
AND | (Preferred AND Securities) | Matches documents where both terms exist |
NOT | (Preferred NOT Securities) | Exclude documents that contain the second term |
OR | (Preferred OR Securities) | Matches documents that contain either term |
Grouping | ((Bond OR Certificate) AND “British Airways”) | Use parentheses to group terms to form sub queries |
Proximity | (preferred w/10 security) | Terms within a specific distance of other terms |
Proximity Ordered | (preferred wo/10 security) | Ensure a term appears near, but after, another term |
? Wildcard | G??D | Match any single character |
* Wildcard | Gold* | Match any number of characters |
The following is key subset of the fields can be used within the ‘q’ parameter itself to build up a Boolean filter expression. See [link: How to Query] for details of how to build up expressions using these fields. A full list of fields can be found in the [link: Data Glossary]
‘company’
Get all clauses for a specific entity – identified by its internal ID – associated with the Issuer.
i.e. companyID: 1022 = Vodafone Group Plc
‘country’
Get all clauses that are relevant for a specific geography using the ‘country’ field. The example below shows how to get all clauses that are relevant for United Kingdom (id:1).
‘sector’
Get all clauses that are relevant for a specific industry. The industry classification is according to FTSE ICB categorisation. The example below shows how to query clauses relevant for the telecommunications sector (id: 6000).
‘market’
Get all clauses that are relevant for a specific market of listing. The example below shows how to query clauses relevant for entities listed on the London Stock Exchange (id:53).
‘ISIN’
Get all clauses that are relevant for a specific ISIN. The example below shows how to query clauses relevant for XS1145855646.
‘issueDate’
To get clauses that have been published on a specific issue date or timeframe, you can set the lower and upper date and time limit. For example, the query below returns all clauses published between 07/09/2019 and 07/09/2020. Use [ ] for your parameters around the date like this:
‘year’
Below is an example query for all clauses found in documents issued in 2019.
‘sort’
Results can be sorted by any field in the payload using the ‘sort’ parameter. Use the field name preceded by a ‘+’ to apply ascending order, and a ‘-‘ to for descending order. For example, to sort by ‘issueDate’ descending, use:
‘levelOfDetail’
Entering a value of high will return all available fields in the response, low will return just a small subset of fields for use when reduced payloads are needed.
‘size’
Controls the number of clauses returned in the payload. Maximum 100.
‘maxTextFieldLength’
Used to truncate long text fields. Useful whilst developing queries. If no value is supplied, then the full text is returned.