Hey everyone, I have an interesting issue I’ve come across with the API. For shows that have multiple time slots, depending on when the API call happens, it returns the the upcoming start time. So if there’s a show that airs Mondays at 6pm and again Fridays at 11am, given that today is Wednesday, the start time would show Friday at 11am. Is there a way to grab a specific air time from the API? Is there something other than “start” that returns a day and time? Thanks!
1 Like
Hi Calvin. Good question! The API for the schedule is complex because scheduled shows can have complicated repetitions.
GET /shows behaves in two different ways:
-
Get all the shows after a given {start} datetime.
Each show appears only once in the API response. It can useful for example to produce a list of all the distinct shows titles.
-
Get all the occurrences of all the shows up to a given {end} datetime.
Each show can appear multiple times in the response, once for each occurrence of the show in the given time range. Use this to produce a display of the date and time that shows will be broadcast.
So to get all the occurrences of a show you have to specify an {end} datetime in the query. For example
curl "https://spinitron.com/api/show?start=monday&end=monday+1week&count=200" -H "Authorization: Bearer YourAPIkey"
We use PHP’s datetime parser that is very flexible and can understand compound and relative expressions like in this example.
I copied below the documentation of the endpoint (correcting all the spelling errors :-/).
Note: API responses have a default page length of 20 items. You can increase it with the count query parameter, as in the example. API responses have a _links object with URLs to pages includes the next page if there is one.
Documentation of GET /shows
Terminology: Spinitron defines a show as a radio program. A show can have one or more schedules, each of which may specify either an occurrence or a repetition, which represents a set of occurrences. Thus scheduled shows have occurrences that, for example, may be displayed in a calendar.
In the response, items is an array of objects representing occurrences of scheduled shows.
You may optionally filter items to a datetime range by including in the request {start} and/or {end} parameters, both of which must be no more than one hour in the past.
items can include occurrences that begin or end within the filter range. A show that goes on air before {start} appears in items if it ends after but not at {start}. An occurrence starting at or before {end} is included.
If the request omits the {start} parameter, the server sets its value to the current time so that the filter range’s start is always defined. If the request specifies {end} then the requested range is bounded, otherwise it is unbounded.
For a bounded request, items includes every occurrence of all shows occurring in the range. The only difference between objects in items representing a given show will be the start field value.
For an unbounded request, items includes only one occurrence per show, specifically, the next occurrence after {start} of all shows occurring after {start}.
Use an unbounded request to get a straight list all shows. Use a bounded request to get a calendar/agenda of shows expanded into occurrences by their schedules and repetitions.
Objects in items are ordered first by datetime and then by id.
2 Likes
Thank you for your reply, tom! So I’ve taken some time to tinker around with the shows call, and I’ve gotten as far as making bounded requests, then filtering by show ID. I find myself having the same problem as before where I can’t specifically call a specific show occurrence. I may have worked out a workaround involving passing a variable from a Wordpress page. Still figuring things out, but you did give me some tools to work with for this as well as something else I was trying to figure out, so a million thanks to you!
1 Like
Glad to be of help, Calvin.
If, hypothetically, the API provided a way to call a specific show occurrence, how would you identify the occurrence in the request?