Common API Requests
Here are some common requests that can retrieve metadata from the CDAPI. Unless otherwise specified, each request will return an array of content instance documents, explained in more detail here.
Note that this request only returns exact (case-sensitive) title matches.
1. LIST OF ACTIVE STORES
https://<ApiEndpoint>/stores-active?api_key=<ApiKey>This is a useful sanity check request. It should always return a list of the active API Stores, including the number of programs, events etc. in those stores. Every request needs an <ApiEndpoint> value and an <ApiKey> value. Simply.TV can provide you with the <ApiEndpoint> of a demo instance of the CDAPI and an <ApiKey> for evaluation purposes. When it comes to providing a metadata service, Simply.TV will create a separate instance of the CDAPI for each customer. If the customer requires bespoke functionality, separate test and production instances will be provided. Simply.TV will supply a fixed <ApiEndpoint> value and a fixed <ApiKey> value for each API instance.
2. LIST OF LINEAR CHANNELS
https://<ApiEndpoint>/stores-active/source/filter?filter={"term":"sourceType","value":"linear"}&numberOfResults=250&api_key=<ApiKey>
The above request should return an array of source Documents containing the details of the linear channels whose metadata is available on the API.
3. SET OF EVENTS ON A LINEAR CHANNEL’S SCHEDULE
https://<ApiEndpoint>/stores-active/contentinstance/event/filter?filter={"criteria":[{"term":"internalIds.sourceId","value":<ChannelID>},{"term":"publishedStartDateTime","value":"<StartDateTime>","operator":"atLeast"},{"term":"publishedStartDateTime","value":"<EndDateTime>","operator":"atMost"}],"operator":"and"}&sorting=[{"criterion":"publishedStartDateTime","direction":"ascending"}] &api_key=<ApiKey>
In the above request:
- <ChannelID> is Simply.TV’s internal (numeric) identifier for a linear channel. Simply.TV will supply a list of IDs for all the channels covered by its metadata service.
- <StartDateTime> is the inclusive start of the time period for which event metadata should be returned, in ISO 8601 format, e.g. 2019-02-21T06:00:00.
- <EndDateTime> is the inclusive end of the time period for which event metadata should be returned, in ISO 8601 format, e.g. 2019-02-22T05:59:59.
4. METADATA FOR PROGRAM WITH SPECIFIC SIMPLY.TV PROGRAM ID
https://<ApiEndpoint>/stores-active/contentinstance/program/filter?filter={"term":"internalIds.programId","value":<ProgramID>}&api_key=<ApiKey>
If Simply.TV’s ID for a specific program is known, the above request can be used to obtain the details of that program.
5. METADATA FOR PROGRAM WITH SPECIFIC THIRD PARTY PROGRAM ID
https://<ApiEndpoint>/stores-active/contentinstance/program/filter?filter={"criteria":[{"term":"thirdPartyIds.type","value":"<ThirdPartyIDType>"},{"term":"thirdPartyIds.value","value":"<ThirdPartyIDValue>"}],"operator":"nestedAnd"}&api_key=<ApiKey>
If Simply.TV has imported a third party’s program IDs, the above request will return the details of the program with the relevant third party ID value. Simply.TV will supply the fixed <ThirdPartyIDType> value where appropriate.
6. METADATA FOR PROGRAM WITH SPECIFIC TITLE AND YEAR OF PRODUCTION
https://<ApiEndpoint>/stores-active/contentinstance/program/filter?filter={"criteria":[{"term":"searchableTitles.value.<LangCode>","value":"<Title>"},{"term":"yearOfProduction","value":<Year>}],"operator":"and"}&api_key=<ApiKey>
In the above request, <LangCode> is the ISO 639-1 (two-character) code for the language of the specified title.Note that this request only returns exact (case-sensitive) title matches.
7. PROGRAM WITH SPECIFIC SERIES TITLE, SEASON NUMBER AND EPISODE NUMBER
https://<ApiEndpoint>/stores-active/contentinstance/program/filter?filter={"criteria":[{"term":"searchableTitles.value.<LangCode>","value":"<Title>"},{"term":"seasonNumber","value":<SeasonNumber>},{"term":"episodeNumber","value":<EpisodeNumber>}],"operator":"and"}&api_key=<ApiKey>
8. PROGRAMS WITH TITLES CONTAINING SPECIFIC WORDS
https://<ApiEndpoint>/stores-active/contentinstance/program/search?query=searchableTitles.value:<SearchWords>&api_key=<ApiKey><SearchWords> should be a list of words separated by spaces, without any enclosing quotes. The request returns full details of all the events featuring programs with a title that includes any of the specified search words. The search is not case-sensitive.
9. METADATA FOR CONTRIBUTOR WITH SPECIFIC SIMPLY.TV CONTRIBUTOR ID
https://<ApiEndpoint>/stores-active/contributor/filter?filter={"term":"contributorId","value":<ContributorID>}&api_key=<ApiKey>
If Simply.TV’s ID for a specific contributor is known, the above request should return the contributor document containing the details of that contributor.