Cinema Premier Agenda

Cinema Premier Agenda

All movie premiers of the week and the following weeks in Portugal.

Buy product  

Technical Overview

Cinema Service

[DEPRECATED]

Search movie and theater show-times by location and other filters. Fetch opening dates for upcoming movies and get in-depth information on movies, theaters, persons and other related data.

About Movie elements:

- Included is a Release element with information on the release in a certain country (defaults to Portugal, but can be overridden if a valid ReleaseCountryId is provided)

API Reference

Download Service WSDL Contract Download Service OSD Contract
Service Operation Description
Cinema GetContributorRoles List contribution roles. Parameters: PageNumber (optional, defaults to 1); RecordsPerPage (optional, defaults to 0);
GetCountryAuthority Get the given country's rating authority details, including the possible movie ratings. Parameters: CountryId (Sapo GIS CountryId);
GetGenres Get movie genres list. Parameters: PageNumber (optional, defaults to 1), RecordsPerPage (optional, defaults to 10);
GetMoviePremieres List movies with premiere data associated. Parameters: ReleaseCountryId (optional, default = PT); StartDate (ex. 2009-07-01, optional, default = start of current week, Sunday 00:00); EndDate (2009-07-01, optional, default = end of current week, Saturday 23:59); ProductionCountryIds (optional, ex. PT,ES); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04,M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10)
GetMoviesWithShowTimes List movies with show-times within the given locations and time period. Parameters: ReleaseCountryId (optional, default = PT); LocationIds (optional, must be within ReleaseCountry, ex. 11,13); StartDate (2009-07-10, optional, default = last Thursday); EndDate (2009-07-01, optional, default = next Thursday); ProductionCountryIds (optional, ex. ES,PT); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04, M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10);
GetPersons List persons according to filters (paginated). IncludeReleaseWithCountryId default = PT; PageNumber default = 1; RecordsPerPage default = 10, Max itens = 20;
GetTheaters List theaters within the the given locations, with amount movies.
GetTheatersWithShowTimes List theaters within the given locations with show-times within the time period. Parametres: ReleaseCountryId (optional, default = PT); LocationIds (optional, must be within ReleaseCountry, ex. 11,13); StartDate (2009-01-01, optional, default = last Thursday); EndDate (2009-09-01, optional, default = next Thursday), ProductionCountryIds (optional, ex. ES,PT); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04, M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10)

Cinema Service

GetContributorRoles

List contribution roles. Parameters: PageNumber (optional, defaults to 1); RecordsPerPage (optional, defaults to 0);

Request Parameters

PageNumber : int (optional)
RecordsPerPage : int (optional)

Response Parameters

GetContributorRolesResult : ListOfContributorRoles (required)

List contribution roles. Parameters: PageNumber (optional, defaults to 1); RecordsPerPage (optional, defaults to 0);
Go to top

GetCountryAuthority

Get the given country's rating authority details, including the possible movie ratings. Parameters: CountryId (Sapo GIS CountryId);

Request Parameters

CountryId : string (required)

Response Parameters

GetCountryAuthorityResult : Authority (required)

Get the given country's rating authority details, including the possible movie ratings. Parameters: CountryId (Sapo GIS CountryId);
Go to top

GetGenres

Get movie genres list. Parameters: PageNumber (optional, defaults to 1), RecordsPerPage (optional, defaults to 10);

Request Parameters

PageNumber : int (optional)
RecordsPerPage : int (optional)

Response Parameters

GetGenresResult : ListOfGenres (required)

Get movie genres list. Parameters: PageNumber (optional, defaults to 1), RecordsPerPage (optional, defaults to 10);
Go to top

GetMoviePremieres

List movies with premiere data associated. Parameters: ReleaseCountryId (optional, default = PT); StartDate (ex. 2009-07-01, optional, default = start of current week, Sunday 00:00); EndDate (2009-07-01, optional, default = end of current week, Saturday 23:59); ProductionCountryIds (optional, ex. PT,ES); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04,M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10)

Request Parameters

ReleaseCountryId : string (optional)
StartDate : date (optional)
EndDate : date (optional)
ProductionCountryIds : ArrayOfProductionCountryId (optional)
GenreIds : ArrayOfGenreId (optional)
ReleaseRatingIds : ArrayOfRatingId (optional)
IncludeContributors : boolean (optional)
IncludeSynopsis : boolean (optional)
PageNumber : int (optional)
RecordsPerPage : int (optional)
Version : int (optional)

Response Parameters

GetMoviePremieresResult : ListOfMovies (required)

List movies with premiere data associated. Parameters: ReleaseCountryId (optional, default = PT); StartDate (ex. 2009-07-01, optional, default = start of current week, Sunday 00:00); EndDate (2009-07-01, optional, default = end of current week, Saturday 23:59); ProductionCountryIds (optional, ex. PT,ES); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04,M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10)

List movies with premiere data associated. Parameters: ReleaseCountryId (optional, default = PT); StartDate (ex. 2009-07-01, optional, default = start of current week, Sunday 00:00); EndDate (2009-07-01, optional, default = end of current week, Saturday 23:59); ProductionCountryIds (optional, ex. PT,ES); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04,M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10)
Go to top

GetMoviesWithShowTimes

List movies with show-times within the given locations and time period. Parameters: ReleaseCountryId (optional, default = PT); LocationIds (optional, must be within ReleaseCountry, ex. 11,13); StartDate (2009-07-10, optional, default = last Thursday); EndDate (2009-07-01, optional, default = next Thursday); ProductionCountryIds (optional, ex. ES,PT); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04, M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10);

Request Parameters

ReleaseCountryId : string (optional)
LocationIds : ArrayOfLocationId (optional)
StartDate : date (optional)
EndDate : date (optional)
ProductionCountryIds : ArrayOfProductionCountryId (optional)
GenreIds : ArrayOfGenreId (optional)
ReleaseRatingIds : ArrayOfRatingId (optional)
IncludeShowTimesDetails : boolean (optional)
IncludeContributors : boolean (optional)
IncludeSynopsis : boolean (optional)
IncludeGenres : boolean (optional)
Disables show details of the genre in the film
IncludeReferences : boolean (optional)
IncludeRelease : boolean (optional)
IncludeMedia : boolean (optional)
Version : int (optional)
PageNumber : int (optional)
RecordsPerPage : int (optional)

Response Parameters

GetMoviesWithShowTimesResult : ListOfMovies (required)

List movies with show-times within the given locations and time period. Parameters: ReleaseCountryId (optional, default = PT); LocationIds (optional, must be within ReleaseCountry, ex. 11,13); StartDate (2009-07-10, optional, default = last Thursday); EndDate (2009-07-01, optional, default = next Thursday); ProductionCountryIds (optional, ex. ES,PT); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04, M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10);
Go to top

GetPersons

List persons according to filters (paginated). IncludeReleaseWithCountryId default = PT; PageNumber default = 1; RecordsPerPage default = 10, Max itens = 20;

Request Parameters

BirthCountryId : string (optional)
IncludeReleaseWithCountryId : string (optional)
SearchTerms : string (optional)
PageNumber : int (optional)
RecordsPerPage : int (optional)

Response Parameters

GetPersonsResult : ListOfPerson (required)
Go to top

GetTheaters

List theaters within the the given locations, with amount movies.

Request Parameters

ReleaseCountryId : string (required)
LocationIds : ArrayOfLocationId (optional)
PageNumber : int (optional)
RecordsPerPage : int (required)

Response Parameters

GetTheatersResult : ListOfTheaters (required)
Go to top

GetTheatersWithShowTimes

List theaters within the given locations with show-times within the time period. Parametres: ReleaseCountryId (optional, default = PT); LocationIds (optional, must be within ReleaseCountry, ex. 11,13); StartDate (2009-01-01, optional, default = last Thursday); EndDate (2009-09-01, optional, default = next Thursday), ProductionCountryIds (optional, ex. ES,PT); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04, M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10)

Request Parameters

ReleaseCountryId : string (optional)
LocationIds : ArrayOfLocationId (optional)
StartDate : date (optional)
EndDate : date (optional)
ProductionCountryIds : ArrayOfProductionCountryId (optional)
GenreIds : ArrayOfGenreId (optional)
ReleaseRatingIds : ArrayOfRatingId (optional)
IncludeShowTimeDetails : boolean (optional)
IncludeLocation : boolean (optional)
PageNumber : int (optional)
RecordsPerPage : int (optional)
Version : int (optional)

Response Parameters

GetTheatersWithShowTimesResult : ListOfTheaters (required)

List theaters within the given locations with show-times within the time period. Parametres: ReleaseCountryId (optional, default = PT); LocationIds (optional, must be within ReleaseCountry, ex. 11,13); StartDate (2009-01-01, optional, default = last Thursday); EndDate (2009-09-01, optional, default = next Thursday), ProductionCountryIds (optional, ex. ES,PT); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, ex. M04, M18); PageNumber (optional, default = 1); RecordsPerPage (optional, default = 10)

List theaters within the given locations with show-times within the time period. Parameters: ReleaseCountryId (optional, default = PT); LocationIds (optional, must be within ReleaseCountry, ex. 11,13); StartDate (2009-01-01, optional, default = last Thursday); EndDate (2009, optional, default = next Thursday); ProductionCountryIds (optional, ex. Es,PT); GenreIds (optional, ex. 2,3); ReleaseRatingIds (optional, PT,ES); PageNumber (optional, default = 1), RecordsPerPage (optional, default = 10);
Go to top

Cinema Entities

ArrayOfContribution

Attribute Name Description
List of Contribution : Contribution (optional)
Go to top

ArrayOfContributor

Attribute Name Description
List of Contributor : Contributor (optional)
Go to top

ArrayOfContributorRole

Attribute Name Description
List of ContributorRole : ContributorRole (optional)
Go to top

ArrayOfCountry

Go to top

ArrayOfExternalId

Attribute Name Description
List of ExternalId : ExternalId (optional)
Go to top

ArrayOfGenre

Attribute Name Description
List of Genre : Genre (optional)
Go to top

ArrayOfGenreId

Attribute Name Description
List of GenreId : string (optional)
Go to top

ArrayOfLink

Attribute Name Description
List of Link : Link (optional)
Go to top

ArrayOfLocationId

Attribute Name Description
List of LocationId : string (optional)
Go to top

ArrayOfMediaItem

Attribute Name Description
List of MediaItem : MediaItem (optional)
Go to top

ArrayOfMovie

Attribute Name Description
List of Movie : Movie (optional)
Go to top

ArrayOfMovieShowTimes

Attribute Name Description
List of MovieShowTimes : MovieShowTimes (optional)
Go to top

ArrayOfPerson

Attribute Name Description
List of Person : Person (optional)
Go to top

ArrayOfProductionCountryId

Attribute Name Description
List of ProductionCountryId : string (optional)
Go to top

ArrayOfQuote

Attribute Name Description
List of Quote : Quote (optional)
Go to top

ArrayOfRating

Attribute Name Description
List of Rating : Rating (optional)
Go to top

ArrayOfRatingId

Attribute Name Description
List of RatingId : string (optional)
Go to top

ArrayOfShowTime

Attribute Name Description
List of ShowTime : ShowTime (optional)
Go to top

ArrayOfTheater

Attribute Name Description
List of Theater : Theater (optional)
Go to top

ArrayOfTheaterShowTimes

Attribute Name Description
List of TheaterShowTimes : TheaterShowTimes (optional)
Go to top

ArrayOfThumbnail

Attribute Name Description
List of Thumbnail : Thumbnail (optional)
Go to top

ArrayOfVersions

Attribute Name Description
List of Version : Version (optional)
Go to top

Authority

Attribute Name Description
Id : string
Name : string
Country : Country (optional)
Ratings : ArrayOfRating (optional)
Go to top

Contact

Attribute Name Description
URL : string (optional)
Email : string (optional)
Phone : string (optional)
CellPhone : string (optional)
Go to top

Contribution

Attribute Name Description
Movie : Movie
Role : ContributorRole
Go to top

Contributor

Attribute Name Description
SourceId : string
Source : string
Go to top

ContributorRole

Attribute Name Description
Id : string
Name : string
Go to top

Country

Go to top

ExternalId

Attribute Name Description
Source : ExternalIdSource
Id : string
Go to top

ExternalIdSource

Value Name Description
Meo
Sercultur
IMDB
Go to top

Genre

Attribute Name Description
Id : string
Name : string
Slug : string (optional)
WorkCount : int (optional)
Go to top

Link

Go to top

ListOfContributorRoles

Attribute Name Description
ContributorRoles : ArrayOfContributorRole
PaginationDetails : PaginationDetails
Go to top

ListOfGenres

Attribute Name Description
Genres : ArrayOfGenre
PaginationDetails : PaginationDetails
Go to top

ListOfMovies

Attribute Name Description
Movies : ArrayOfMovie
PaginationDetails : PaginationDetails
Go to top

ListOfPerson

Attribute Name Description
Persons : ArrayOfPerson
PaginationDetails : PaginationDetails
Go to top

ListOfTheaters

Attribute Name Description
Theaters : ArrayOfTheater
PaginationDetails : PaginationDetails
Go to top

Location

Attribute Name Description
CountryId : string (optional)
CountryName : string (optional)
DistrictId : string (optional)
DistrictName : string (optional)
MunicipalityId : string (optional)
MunicipalityName : string (optional)
ParishId : string (optional)
ParishName : string (optional)
Latitude : float (optional)
Longitude : float (optional)
Metadata : LocationMetadata (optional)
ZipCode : string (optional)
Locality : string (optional)
Street : string (optional)
HouseNumber : string (optional)
MatchLevel : string (optional)
Go to top

LocationMetadata

Attribute Name Description
Provider : string
TrustLevel : string (optional)
ISP : string (optional)
Go to top

MediaCategory

Value Name Description
Poster
Trailer
Image
Video
Go to top

MediaItem

RandName é o identificador único de um vídeo na plataforma SAPO Videos. Para mais informação, consultar: http://services.sapo.pt/Metadata/Service/Videos
Attribute Name Description
Type : MediaType
Category : MediaCategory
Name : string (optional)
URL : string (optional)
RandName : string (optional)
Extension : string (optional)
Width : float (optional)
Height : float (optional)
Thumbnails : ArrayOfThumbnail (optional)
Go to top

MediaType

Value Name Description
Image
Video
Go to top

Movie

Attribute Name Description
Id : string
Url : string (optional)
Title : string (optional)
Release : Release (optional)
Year : int (optional)
ProductionCountries : ArrayOfCountry (optional)
Runtime : int (optional)
Synopsis : string (optional)
Contributors : ArrayOfContributor (optional)
Genres : ArrayOfGenre (optional)
Media : ArrayOfMediaItem (optional)
References : References (optional)
TheaterShowTimesList : ArrayOfTheaterShowTimes (optional)
CreateDate : dateTime
UpdateDate : dateTime (optional)
Quotes : ArrayOfQuote (optional)
Version : int (optional)
VersionAbbr : string (optional)
Versions : ArrayOfVersions (optional)
Rating : int (optional)
Go to top

MovieShowTimes

Attribute Name Description
Movie : Movie
ShowTimes : ArrayOfShowTime
TheaterTicketOfficeURL : string (optional)
Go to top

PaginationDetails

Attribute Name Description
CurrentPage : integer
RecordsPerPage : integer
RecordsTotal : integer
Go to top

Person

Attribute Name Description
Id : string
Url : string (optional)
Name : string
BornDate : date (optional)
DiedDate : date (optional)
Country : Country (optional)
Biography : string (optional)
Media : ArrayOfMediaItem (optional)
Contributions : ArrayOfContribution (optional)
CreateDate : dateTime (optional)
UpdateDate : dateTime (optional)
Go to top

Quote

Attribute Name Description
Title : string
CharacterName : string
Movie : Movie (optional)
Go to top

Rating

Attribute Name Description
Id : string
Name : string
Go to top

References

Attribute Name Description
ExternalIds : ArrayOfExternalId (optional)
Links : ArrayOfLink (optional)
Go to top

Release

Attribute Name Description
Country : Country
Title : string (optional)
Distributor : string (optional)
ReleaseDate : dateTime (optional)
Rating : Rating (optional)
Authority : Authority (optional)
Go to top

ShowTime

Attribute Name Description
TimeStart : dateTime
ShowTimeTicketOfficeURL : string (optional)
Go to top

Theater

Attribute Name Description
Id : string
Name : string
Contact : Contact (optional)
TicketOfficeURL : string (optional)
Location : Location (optional)
Description : string (optional)
MovieShowTimesList : ArrayOfMovieShowTimes (optional)
CreateDate : dateTime
UpdateDate : dateTime (optional)
MoviesTotal : int (optional)
Go to top

TheaterShowTimes

Attribute Name Description
Theater : Theater
ShowTimes : ArrayOfShowTime
TheaterTicketOfficeURL : string (optional)
Go to top

Thumbnail

Attribute Name Description
Name : string (optional)
URL : string
Width : float
Height : float
Go to top

Version

Attribute Name Description
Id : int
Abbr : string
IsMain : boolean
Go to top

REST API Authentication

Authenticating REST Request

Every request must contain authentication information to establish the identity of whom making the request and a autorization token denominated ESBAccessKey.

ESB Access Key

The ESB Access Key is what will authorize the usage of the API and is available when the buying process ends. In the costumer area you can find the product details where you can generate an ESB Access Key for you usage, another user registered on SAPO Services or even for everyone.

The element ESBAccessKey must appear on the URL as a query-string

HTTP GET example using username and password:

HTTP POST username and password:

Request with ESBToken

Using a token instead of your username and password can be useful if you don't want to give your credentials to whom is using the API.

In order to generate a ESB Token you must use SAPO Security Token Service. The ESBToken is valid for 12 hours.

HTTP GET example using ESB Token:

HTTP POST ESB Token:

Parameters description

ESBCredentials are parameters used to authenticate and authorize a REST request

Elements Description
ESBUsername The e-mail of the account that is used to access the API.
ESBPassword The password that in combination with the ESBUsername is used to access the corresponding account.
ESBToken An authentication token generated by using an user name (ESBUsername) and password (ESBPassword). It should be used a ESBToken or the combination of ESBUsername and ESBPassword.
ESBAccessKey The authorization key used to authorize the request against your purchase. The account being used to access the service must be associated to this key.
Go to top

SOAP API Authentication

Authenticating SOAP Request

Every request must contain authentication information to establish the identity of whom making the request and a autorization token called ESB Access Key.

ESB Access Key

Correct with the path to the access key

The ESB Access Key is what will authorize the usage of the API and is available when the buying process ends. In the costumer area you can find the product details where you can generate an ESB Access Key for you usage, another user registered on SAPO Services or even for everyone.

The element ESBAccessKey must appear on the message SOAP Header after the complex type ESBCredentials

Example:

ESBCredentials

ESBCredentials is a complex type that is used to pass the credentials in order to authenticate a SOAP request.

Request with username and password
Elements Description
ESBUsername The e-mail of the account that is used to access the API
ESBPassword The password that in combination with the ESBUsername is used to access the corresponding account

Example:

Request with ESBToken

Using a token instead of your username and password can be useful if you don't want to give your credentials to whom is using the API.

In order to generate a ESB Token you must use SAPO Security Token Service (STS). The ESBtoken is valid for 12 hours.

Requesting with an ESBtoken
Go to top