Cineteca di Bologna API: CINEMA S SCHEDULING

Transcription

1 Cineteca di Bologna API: CINEMA S SCHEDULING Revision: 1 Release date: Oct 31 st, 2014 License: Creative Commons No Rights Reserved (CC0) Abstract This set of APIs allow you to query Cineteca di Bologna s projections and events programme..

2 Introduction Cineteca di Bologna s programme is organized into events (ie. Cinema Ritrovato) that can belong to a bigger event (collector), movies projections that can belong to none, one or several events and have one or several projection times. The following APIs allow you to: GetCurrentEvents: retrieve a list of current events with codes to be used as filters in the following API; GetSchedule: retrieve a list of projections based on time, keyword and events filters. Please note that all text in the database (descriptions, etc.) is written in Italian language. GetCurrentEvents API request method Request URL: The API has no parameters and provides the list of all events under way at the moment of request. GetCurrentEvents API response The response is an XML file with the following structure: Where: <?xml version="1.0" encoding="iso "?> <Event> <ID>[EventID]</ID> <Title>[Title]</Title> <Subtitle>[Subtitle]</Subtitle> <HumanReadableDates>[DateText]</HumanReadableDates> <EndDate>[EndDate]</EndDate> <Thumbnail>[ImageUrl]</Thumbnail> <Abstract>[Abstract]</Abstract> <URL>[EventUrl]</URL> <ParentID>[ParentEventID]</ParentID> </Event> <Event> </Event> [EventID]: identifier of the event, to be used as filter in the GetSchedule API; [Title]: event s name/title;

3 [Subtitle]: event s subtitle; [DateText]: a string containing a human readable date and occasionally place specification (i.e. Bologna, dal 4 al 9 marzo 2015 ); [EndDate]: event ending date in format YYYY-MM-DD; [ImageUrl]: URL of a small picture (or logo) representing the event, usually JPG, PNG or GIF; [Abstract]: a brief description of the event, may contain HTML formatting; [Url]: the URL of the event page on Cineteca di Bologna s website; [ParentEventID]: ID of the event s collector, if the event does not belong to any other event the tag is empty. GetSchedule API request method Request URL: MM-DD&enddate=YYYY-MM-DD&event=[ID]&keyword=[String] The API can be invoked without or with any of the following parameters: startdate: set a date if you want to specify the starting date of a specific period, if no start date is provided the default is the current day; enddate: set a date if you want to specify an ending date of a specific period, if no date is provided the default value is the end of time; please note that you can expect a month or maximum two monthes of scheduled events in the future; event: set an ID (retrieved with the previous API) if you want to retrieve only projections of the specific event; keyword: set a keyword if you want to retrieve events containing that keyword in Title or Abstract. If more than one parameter is set, the API will respond with scheduling that matches all of the set parameters. GetCurrentEvents API response The response is an XML file with the following structure: <?xml version="1.0" encoding="iso "?> <Scheduling> <Schedule> <ID>[ID]</ID> <Title>[Title]</Title> <Subtitle>[Subtitle]</Subtitle> <Type>[Type]</Type> <Thumbnail>[ImageUrl]</Thumbnail> <Abstract>[Abstract]</Abstract> <LocationName>[LocationName]</LocationName> <LocationAddress>[LocationAddress]</LocationAddress> <LocationGPS>[Latitude],[Longitude]</LocationGPS> <FlagItalianPrimetime>[Primetime]</FlagItalianPrimetime>

4 Where: <FlagFIC>[Fic]</FlagFIC> <FlagCinefilia>[Cinefilia]</FlagCinefilia> <FlagChildren>[Children]</FlagChildren> <FlagTeens>[Teens]</FlagTeens> <FlagOriginalLanguage>[Language]</FlagOriginalLanguage> <FlagOrchestra>[Orchestra]</FlagOrchestra> <Timetable> <DateTime>[ScheduleTime]</DateTime> <DateTime> </DateTime> <Timetable> <ParentEvent>[EventID]</ParentEvent> <ParentEvent> </ParentEvent> </Events> <URL>[PageUrl]</URL> </Schedule> <Schedule> </Schedule> </Scheduling> [ID]: ID of the movie; [Title]: movie title; [Subtitle]: movie subtitle; [Type]: can be movie (for regular projections) or occasionally unspecified in case the scheduling is for a presentation, meeting or generally non-projection events; [ImageUrl]: URL of a small picture (or logo) representing the event, usually JPG, PNG or GIF; [Abstract]: a brief description of the event, may contain HTML formatting; [LocationName]: name of the venue the event takes place in; [LocationAddress]: string with full address of the venue; [Latitude] and [Longitude]: GPS coordinates of the venue; [Primetime]: a flag (can be 0 or 1) set to 1 if the projection is a prime time in Italy; [Fic]: a flag (can be 0 or 1) set to 1 if the projection is reserved to FIC members; [Cinefilia]: a flag (can be 0 or 1) set to 1 if the projection belongs to Cinefilia; [Children]: a flag (can be 0 or 1) set to 1 if the projection is suggested for children; [Teens]: a flag (can be 0 or 1) set to 1 if the projection is suggested for teens; [Language]: a flag (can be 0 or 1) set to 1 if the projection is in original non-italian language with Italian subtitles; [Orchestra]: a flag (can be 0 or 1) set to 1 if the projection is accompanied by live orchestra;

5 [ScheduleTime]: date and time of the projection in the format YYYY-MM-DD HH:MM:SS, please note that a projection may be scheduled several times and thus contain several <DateTime> items/tags, please also note that if you query for a specific period, all movies with at least one projection time in that period are listed in the XML and all of their projection times are listed anyway, even if they do not belong to the queried period; [EventID]: ID of the event the projection belongs to, you can retrieve more information on the event by using the GetCurrentEvents API, please note that a movie can belong to one or several events (in this case <ParentEvent> item is repeated) or to no events (in this case the item is empty); [PageUrl]: the URL of the projection s page on Cineteca di Bologna s website.