getData |
This is the most universal method to request data from any specific table. The result set can be restricted to certain columns or rows (using filters), and it can be sorted.
Request
parameters |
|---|
table Required |
Type: string or int
Identifies the table (by ID or internal table name) from which data is requested. Commonly used tables are: accreditation, event, film, filmCopy, location, organization, program, programLine, user, viewing. See Filmchief System Security Table-level permission defaults for a complete list of existing tables. You will find the internal table name of any table on its details page.
|
columns |
Type: string
Comma-separated string of requested column names. Available columns vary across festivals; in Filmchief, see the details page of the selected table to find out which columns are available. If not set, all columns are included.
|
filters |
Type: string
Filters can be used to restrict the data by certain criteria. You can define one or more filter using a special filter syntax. There are different types of filters, for various types of columns:
Foreign key filters
Columns that directly refer to another table can be filtered like this:
value -column film.submittedForEvent [10]
This filter selects films that were submitted for the event with ID 10. To select all films that were submitted for two events, you can comma-separate the ID values:
value -column film.submittedForEvent [9,10]
This filter selects films that were submitted for the event with ID 9 or 10.
Tags (many-to-many relations) filters
To filter by labels/tags or other fields with a many-to-many relationship, use the option-values filter to find records with matching IDs:
option-values -column film.shownInEvents [10]
This filter selects films that were screened in the event with ID 10. Again, use commas to separate multiple IDs:
option-values -column film.shownInEvents [9,10]
This filter selects films that were screened in the event with ID 9 or 10.
Tags filter modes
For tags filters, the -mode parameter controls how the filter works. Possible options are:
or: checks if any of the specified values matchand: checks if all of the specified values matchnot: checks if none of the specified values match
Some examples:
option-values -column film.shownInEvents -mode and [9,10]
This filter selects films that were screened both in the event with ID 9 and 10.
option-values -column film.shownInEvents -mode not [9,10]
This filter selects films that were neither screened in the event with ID 9 nor 10.
Filtering tags by abbreviation
Some labels (tags) have an Abbreviation, which makes them easier to filter. Instead of option-values, use abbreviation to filter by the abbreviation of tags. For example:
abbreviation -column event.eventType ["main"]
This filter selects events with event type "Main event" using the abbreviation of the "event type" label.
Finding records with no tags
To include the Not set option in your filter, use the null keyword as a filter value. For example:
option-values -column event.eventType [null]
This filter selects events with no event type. This also works with the abbreviation filter.
Range filters
Use a range filter to find records with a value between a certain range.
range -column review.rating -min 2 -max 4
This filter selects reviews with a rating between 2 and 4.
range -column history.lastCascadedChange -min 2021-05-09 00:00:00
This filter selects records from the history table for rows that were changed (directly or indirectly) since 9 May 2021.
Text filters
text -column film.originalTitle -mode contains ["now"]
This filter selects films of which the Original title contains the text 'now'.
Text filter modes
For text filters, the -mode parameter controls how the text filter works. Possible options are:
contains: checks if the specified text occurs in the specified columndoes-not-contain: checks if the specified text doesn't occur in the specified columnempty: checks if the cell is emptynonempty: checks if the cell is non-empty
Combining multiple filters
Multiple filters are separated with a | character.
option-values -column film.shownInEvents [10]|abbreviation -column film.premiere -mode not [null,"no-premiere"]
This filter selects films that were screened in the event with ID 10, with any Premiere tag.
|
orderBy |
Type: string
Comma-separated string of column names to sort the data by, optionally suffixed with + (ascending) or - (descending) to indicate sort direction.
|
limitStart |
Type: int
The row number after which the limited rows are returned. Note: An orderBy clause is not required; however, without an orderBy clause, the results are non-deterministic because results within a result set are not necessarily in any particular order. To control the results returned, use an orderBy clause.
|
limitCount |
Type: int
The number of rows returned. Note: An orderBy clause is not required; however, without an orderBy clause, the results are non-deterministic because results within a result set are not necessarily in any particular order. To control the results returned, use an orderBy clause.
|
Response
response fields |
|---|
* |
All requested columns.
|
Example:
The following example retrieves event ID, name, publication level, start and end date of all main events, sorted by descending start date:
<?php
$params = array(
'token' => $filmchiefApiConnection['token'],
'proc' => 'getData',
'table' => 'event',
'columns' => 'eventID,name,publicationLevel,startDate,endDate',
'filters' => 'abbreviation -column event.eventType ["main"]',
'orderBy' => 'startDate-'
);
$url = 'https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?' . http_build_query($params);
$data = json_decode(file_get_contents($url), true);
?>
https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?token=«token»&proc=getData&table=event&columns=eventID,name,publicationLevel,startDate,endDate&filters=abbreviation%20-column%20event.eventType%20["main"]&orderBy=startDate-
|
getTicketingDetails |
Requests information relevant for ticketing of one or more viewings.
Note: if eventID, programID and viewingID are not set, then all viewings in all current and future events are selected.
Request
parameters |
|---|
eventID |
Type: int
If set, results are restricted to viewings that are part of the requested event.
|
programID |
Type: int
If set, results are restricted to viewings of the requested program.
|
viewingID |
Type: string
If set, results are restricted to the requested viewing (or comma-separated viewings) only.
|
currentUserID |
Type: int
ID of the currently signed in user. If there are price levels available only to this user, they will be included in the results.
|
pointOfSaleTypes |
Type: string
Comma-separated ID values or abbreviation values of point of sale types to filter ticket types and price levels by.
If you are integrating ticketing in your festival site, specify online to restrict to tickets that are available online.
|
lang |
Type: string
ID or code of the current interface language, e.g. 'en' or 'nl'.
|
onSaleNow |
Type: int
Set to 1 to exclude tickets that are no longer / not yet available.
|
addSeconds |
Type: int
Simulates another time by adding or subtracting seconds. Useful for previewing and debugging.
|
Response
response fields |
|---|
* |
Type: array
The data object is an array of requested viewings, including ticketing information. Each element consists of the following properties:
viewingID |
Type: int
The ID of the viewing.
|
startDateTime |
Type: string (datetime)
Date and time this viewing starts. Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
|
locationLabel |
Type: string
The location where the viewing takes place.
|
programTitle |
Type: string
Title of the program. Based on the lang parameter or the language preferences of the current user, the translated version is returned if applicable.
|
programSubtitle |
Type: string
Secondary title of the program. Based on the lang parameter or the language preferences of the current user, the translated version is returned if applicable.
|
programShortDescription |
Type: string (html)
Short description of the program. Based on the lang parameter or the language preferences of the current user, the translated version is returned if applicable.
|
programLongDescription |
Type: string (html)
Long description of the program. Based on the lang parameter or the language preferences of the current user, the translated version is returned if applicable.
|
saleStartDateTime |
Type: string (datetime)
Date and time when ticket sales for this viewing start. Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
|
saleEndDateTime |
Type: string (datetime)
Date and time when ticket sales for this viewing (of any type or price level) end. This also takes into account the viewing’s start date/time and the Checkout deadline (global value or viewing-specific override). Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
|
onSaleNow |
Type: int (0 or 1)
Indicates if tickets for this viewing (of any type or price level) are on sale right now (or at the simulated time, if addSeconds is set to a non-zero value). This takes into account the sale period, as well as the viewing’s start date/time and the global Checkout deadline setting. For example, if a viewing starts at 17:00 and the checkout deadline is set to -15, then (online) ticket sales end at 16:45.
|
currencySymbol |
Type: string
Currency symbol to use when displaying price information (see priceAmount below).
|
ticketsRemaining |
Type: int
The total number of tickets remaining for this viewing.
If this value is 0, it means that tickets for this viewing are sold out; make sure to communicate this with your customers.
If tickets are almost running out, you can display an "Almost sold out!" notification to encourage customers to hurry up.
|
ticketingDetails |
Type: array
Array of available ticket types and price levels for this viewing. Each element has the following properties:
productID |
Type: int
The ID of the product (ticket type).
|
productName |
Type: string
Name of this product, e.g. "Regular ticket".
|
productDescription |
Type: string
Description of this product, e.g. "Regular ticket price for online sales".
|
promotionID |
Type: int
The ID of the promotion (= price level), if any.
|
promotionName |
Type: string
Name of this price level, e.g. "Early bird reduction".
|
promotionDescription |
Type: string
Description of this product, e.g. "Special reduced price (20% off) For our early bird customers.".
|
saleStartDateTime |
Type: string (datetime)
Date and time when ticket sales of this ticket type and price level (if set) start. Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
|
saleEndDateTime |
Type: string (datetime)
Date and time ticket sales for this viewing of this ticket type and price level (if set) end. This also takes into account the viewing’s start date/time and the Checkout deadline (global value or viewing-specific override). Date and time are formatted as ISO 8601 with UTC time zone identifier 'Z': yyyy-mm-ddThh:mm:ssZ.
|
onSaleNow |
Type: int (0 or 1)
Indicates if tickets for this viewing of this ticket type and price level (if set) are on sale right now. This takes into account the sale period, as well as the viewing’s start date/time and the Checkout deadline (global value or viewing-specific override). For example, if a viewing starts at 17:00 and the checkout deadline is set to -15, then (online) ticket sales end at 16:45.
|
priceAmount |
Type: decimal(7,2)
Effective price per ticket (including VAT).
|
priceNote |
Type: string
Additional information about the specified price, e.g. "40% discount".
|
promotionAccreditationListID |
Type: int
The ID of a list that defines which guests (accreditations) are eligible for this price level.
If this value is not null, you can inform your customer that "Conditions apply" or something along those lines. On the Cart and Checkout pages, Filmchief will verify if the customer is actually eligible.
|
promotionCodeSets |
Type: string
Comma-separated IDs of promotion code sets applicable to this price level.
If this value is not null, you can display a "Promotion code required" notification. On the Cart page, the customer can enter the required promotion code.
|
|
|
Example:
The following example retrieves online ticketing information of all viewings in a particular program (with programID = 598) for the currently signed in user.
Note how the value for currentUserID is taken from the $_SESSION['«FESTIVAL IDENTIFIER».filmchief.com'] object, which is automatically defined if SSO is enabled for your website (please see the Single sign-on documentation).
<?php
// By default, assume no user is currently signed in:
$currentUserID = null;
// Check if session information from Filmchief is available:
if (isset($_SESSION['«FESTIVAL IDENTIFIER».filmchief.com'])
&& isset($_SESSION['«FESTIVAL IDENTIFIER».filmchief.com']['userID'])) {
// Get the ID of the currently signed in user (at the Filmchief Portal):
$currentUserID = $_SESSION['«FESTIVAL IDENTIFIER».filmchief.com']['userID'];
}
// Define API call parameters:
$params = array(
'token' => $filmchiefApiConnection['token'],
'proc' => 'getTicketingDetails',
'programID' => 598,
'currentUserID' => $currentUserID,
'pointOfSaleTypes' => 'online',
'onSaleNow' => 1
);
// Contruct the API call URL:
$url = 'https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?' . http_build_query($params);
// Retrieve and decode the API call results:
$data = json_decode(file_get_contents($url), true);
?>
https://«FESTIVAL IDENTIFIER».filmchief.com/api/php/Reader?token=«token»&proc=getTicketingDetails&programID=598¤tUserID=«currentUserID»&pointOfSaleTypes=online&onSaleNow=1
Example response:
{
"data": [
{
"viewingID": 698,
"startDateTime": "2019-11-15 12:00:00Z",
"locationLabel": "Ketelhuis 1",
"programTitle": "Dutch Classics I: Musical Encounters",
"programSubtitle": "",
"programShortDescription": null,
"programLongDescription": null,
"onSaleNow": 1,
"saleStartDateTime": "2020-09-03T11:00:00Z",
"saleEndDateTime": "2019-11-15T11:45:00Z",
"currencySymbol": "€",
"ticketingDetails": [
{
"productID": 11,
"saleStartDateTime": "2019-09-02T14:29:00Z",
"productName": "Regular Ticket Test",
"productDescription": "Regular Ticket Test",
"saleEndDateTime": "2019-11-15T11:45:00Z",
"promotionID": null,
"promotionName": null,
"promotionDescription": null,
"priceAmount": 10,
"priceNote": null,
"promotionAccreditationListID": null,
"promotionCodeSets": null
},
{
"productID": 12,
"saleStartDateTime": "2019-09-02T14:33:00Z",
"productName": "Student Tickets Test",
"productDescription": "Student Tickets Test",
"saleEndDateTime": "2019-11-15T11:45:00Z",
"promotionID": null,
"promotionName": null,
"promotionDescription": null,
"priceAmount": 8,
"priceNote": null,
"promotionAccreditationListID": null,
"promotionCodeSets": null
},
{
"productID": 13,
"saleStartDateTime": "2019-09-02T14:39:00Z",
"productName": "Kid Tickets Test",
"productDescription": "Kid Tickets Test",
"saleEndDateTime": "2019-11-15T11:45:00Z",
"promotionID": null,
"promotionName": null,
"promotionDescription": null,
"priceAmount": 6.5,
"priceNote": null,
"promotionAccreditationListID": null,
"promotionCodeSets": null
}
],
"ticketsRemaining": 143
},
{
"viewingID": 699,
"startDateTime": "2019-11-16 12:00:00Z",
"locationLabel": "Ketelhuis 3",
"programTitle": "Dutch Classics I: Musical Encounters",
"programSubtitle": "",
"programShortDescription": null,
"programLongDescription": null,
"onSaleNow": 1,
"saleStartDateTime": "2019-09-02T14:29:00Z",
"saleEndDateTime": "2019-11-16T11:45:00Z",
"currencySymbol": "€",
"ticketingDetails": [
{
"productID": 11,
"saleStartDateTime": "2019-09-02T14:29:00Z",
"productName": "Regular Ticket Test",
"productDescription": "Regular Ticket Test",
"saleEndDateTime": "2019-11-16T11:45:00Z",
"promotionID": null,
"promotionName": null,
"promotionDescription": null,
"priceAmount": 10,
"priceNote": null,
"promotionAccreditationListID": null,
"promotionCodeSets": null
},
{
"productID": 12,
"saleStartDateTime": "2019-09-02T14:33:00Z",
"productName": "Student Tickets Test",
"productDescription": "Student Tickets Test",
"saleEndDateTime": "2019-11-16T11:45:00Z",
"promotionID": null,
"promotionName": null,
"promotionDescription": null,
"priceAmount": 8,
"priceNote": null,
"promotionAccreditationListID": null,
"promotionCodeSets": null
},
{
"productID": 13,
"saleStartDateTime": "2019-09-02T14:39:00Z",
"productName": "Kid Tickets Test",
"productDescription": "Kid Tickets Test",
"saleEndDateTime": "2019-11-16T11:45:00Z",
"promotionID": null,
"promotionName": null,
"promotionDescription": null,
"priceAmount": 6.5,
"priceNote": null,
"promotionAccreditationListID": null,
"promotionCodeSets": null
}
],
"ticketsRemaining": 50
},
{
"viewingID": 700,
"startDateTime": "2019-11-17 12:00:00Z",
"locationLabel": "Machinegebouw Grote zaal (4)",
"programTitle": "Dutch Classics I: Musical Encounters",
"programSubtitle": "",
"programShortDescription": null,
"programLongDescription": null,
"onSaleNow": 1,
"saleStartDateTime": "2019-09-02T14:29:00Z",
"saleEndDateTime": "2019-11-17T11:45:00Z",
"currencySymbol": "€",
"ticketingDetails": [
{
"productID": 11,
"saleStartDateTime": "2019-09-02T14:29:00Z",
"productName": "Regular Ticket Test",
"productDescription": "Regular Ticket Test",
"saleEndDateTime": "2019-11-17T11:45:00Z",
"promotionID": null,
"promotionName": null,
"promotionDescription": null,
"priceAmount": 10,
"priceNote": null,
"promotionAccreditationListID": null,
"promotionCodeSets": null
},
{
"productID": 12,
"saleStartDateTime": "2019-09-02T14:33:00Z",
"productName": "Student Tickets Test",
"productDescription": "Student Tickets Test",
"saleEndDateTime": "2019-11-17T11:45:00Z",
"promotionID": null,
"promotionName": null,
"promotionDescription": null,
"priceAmount": 8,
"priceNote": null,
"promotionAccreditationListID": null,
"promotionCodeSets": null
},
{
"productID": 13,
"saleStartDateTime": "2019-09-02T14:39:00Z",
"productName": "Kid Tickets Test",
"productDescription": "Kid Tickets Test",
"saleEndDateTime": "2019-11-17T11:45:00Z",
"promotionID": null,
"promotionName": null,
"promotionDescription": null,
"priceAmount": 6.5,
"priceNote": null,
"promotionAccreditationListID": null,
"promotionCodeSets": null
}
],
"ticketsRemaining": 180
}
],
"accepted": true
}
|
