Vocab Search API
The FLOW Vocab Search API provides an endpoint to search the archive of vocabs in FLOW for a given publication. This is for use for delivering frontend website search. The results are ordered by last updated date.
Endpoint
## Vocab Search
/api/vocab/{vocabName}/{publicationDomain}
Available Vocabs
There are a few ways of getting this, firstly is an endpoint that gives either all the vocabs or the vocabs filtered by domain, this is the prefered way.
You can also get them fro the publication object, the vocabs that are available to the publication can be found on the publications full response.
There is a property called vocabs that contains an array of vocab names.
## From the vocabs endpoint, first is unfiltered, 2nd has the publication domain and filters by that
/api/vocabs
/api/vocabs/{publicationDomain}
## From Publication object
/api/publications/{publicationDomain}
where publicationDomain is the domain e.g. example.com
Arguments
Each publication and term combination contains the number of articles tagged with that term.
This applies to Authors, Topics and Sections only
We use similar logic to store which layouts are used per publication for each of these terms, the layouts pX values are the ID of the layout for that term ad publication combination or 0 if there is none .
This is shown in the term's json as layouts.p1 or articleCounts.p1 for example and is used for sorting.
Ordering by articleCounts.p0 allows you to order by the total number of articles attached to the term regardless of publication.
If you don't want to sort by this value then do not supply a sort query string.
You can also optionally filter by hasLayout and hasArticles and they both accept a value of 0 or 1.
| Arguments | Description | Example |
|---|---|---|
| q | Query for keywords | Test Search |
| limit | Set the number of vocab to be return | 20 |
| offset | Set the offset e.g. return vocab from position 40 | 40 |
| startsWith | (Single character) Filter results by matching starting character | a |
| sort | layouts.p1 or articleCounts.p1, p followed by the numeric ID of the publication | layouts.p1 or articleCounts.p1 |
| direction | asc or desc | desc |
| hasLayout | 0 or 1, whether the term should have a layout or not, if so the layout ID is returned | 0 or 1 |
| hasSidebar | 0 or 1, whether the section should have a sidebar or not, if so the sidebar ID is returned | 0 or 1, only works on Sections |
| hasArticles | 0 or 1, whether the term has any articles using it | 0 or 1 |
Full API call based on example above:
Getting the whitelisted vocabs for the indy:
https://indy-api-dev.brightsites.co.uk/api/vocabs/independent.co.uk
Using q:
https://indy-api-dev.brightsites.co.uk/api/vocab/sections/independent.co.uk?q=Football&limit=30&offset=0
Using startsWith:
https://indy-api-dev.brightsites.co.uk/api/vocab/sections/independent.co.uk?startsWith=F&limit=30&offset=0
Sorting:
https://indy-api-dev.brightsites.co.uk/api/vocab/sections/independent.co.uk?sort=articleCounts.p1&direction=desc
Layout, Sidebars and Articles:
https://indy-api-dev.brightsites.co.uk/api/vocab/sections/independent.co.uk?sort=articleCounts.p1&direction=desc&hasLayout=0&hasArticles=1
https://indy-api-dev.brightsites.co.uk/api/vocab/sections/independent.co.uk?sort=articleCounts.p1&direction=desc&hasLayout=1&hasArticles=1
https://indy-api-dev.brightsites.co.uk/api/vocab/sections/independent.co.uk?sort=articleCounts.p1&direction=desc&hasArticles=0
https://indy-api-dev.brightsites.co.uk/api/vocab/sections/independent.co.uk?sort=articleCounts.p1&direction=desc&hasSidebar=1