API Overview


Firstly, what is an API?


You’ve likely seen the term “API” come up. Operating system, web browser, and app updates often announce new APIs for developers. But what is an API?

The term API is an acronym, and it stands for “Application Programming Interface.” It basically allows two applications to talk to each other - in this case the Fantastic for Families website and yours.

Our API allows you to integrate listings published on Fantastic for Families across onto your own website. Fantastic for Families listings can be integrated with your own existing listings or displed as a standalone feed to help increase the amount of content on your site.

You can also filter out listings initially to only show those that are relevant to your organisation (if required). You can then use the event properties to allow users to refine the results further and find events suited to them.

The documentation below contains the details that should be passed onto your website developer for them to be able to integrate Fantastic for Families listings onto your website.

It gets quite nerdy so don't be surprised if, unless you're a website whizz, you don't follow all of it - it's like a secret language!

Requesting access

If you work for a website or publication that features, or would like to feature, family events and places to go, you can request access to the Fantastic for Families API. Please email us at info@fantasticforfamilies.com with details of your organisation and we'll be in touch.

Instructions for personalising event feeds

Please find below descriptions of the results format, and on the parameters that you can use to filter the event data e.g. by location, art-form, or age-range. You may apply multiple filters to the data if required.

To add a filter, please add & followed by the property you wish to filter to the end of the API address, followed by the parameter you wish to filter by. You will need to add & before the property and = before the parameter.

For example, to show only theatre events enter: &artForm=theatre

Your full API URL would therefore be: http://fantasticforfamilies.com/api/events?token=[add token here]&artform=theatre

Notes for web developers

  • q is case-insensitive
  • fromDate is in ISO 8601 format, default format is UTC +0
  • minAge shows events with MaxYear >= minAge
  • maxAge shows events with MinYear <= maxAge
  • DateTime values are of the form /Date(...)/ where ... is Unix time in milliseconds
    • Date and time in UTC: 2020-08-14T13:56:59+...
    • Date without year: --08-14
    • Date: 2020-08-14
  • ReadMoreLink and OrgWebsite values are made available upon request

Further examples of filters

I only want to show events in Wales:
https://fantasticforfamilies.com/api/events?token=e941acc7-dc76-4afc-bcec-6d9a5f30cadf&lat=52.1307&lng=-3.7837

I only want to show events for 0-8 year olds in London:
https://fantasticforfamilies.com/api/events?token=e941acc7-dc76-4afc-bcec-6d9a5f30cadf&minAge=0&maxAge=8&lat=51.5074&lng=-0.1278

I only want to show free events in the London:
https://fantasticforfamilies.com/api/events?token=e941acc7-dc76-4afc-bcec-6d9a5f30cadf&isFree=true&lat=51.5074&lng=-0.1278

I only want to show Age-Friendly Art events in Birmingham:
https://fantasticforfamilies.com/api/events?token=e941acc7-dc76-4afc-bcec-6d9a5f30cadf&ageFriendly=true&artForm=art&lat=52.4862&lng=-1.8904

I only want to show dates within October:
https://fantasticforfamilies.com/api/events?token=e941acc7-dc76-4afc-bcec-6d9a5f30cadf&fromDate=2021-10-01

Parameters

Example filter using the param “q”

http://fantasticforfamilies.com/api/events?token=8fac53b3-1329-45bf-a31c-9aeca2f476ff&q=title+of_venue+or+event

A token must be generated by the administrator as you have to pass the token as a parameter to access any data

Property Required DataType Description
token Yes Guid The key that will grant you access to data
q No String Text search on title of event and title of venue
fromDate No DateTime Minimum date to search from
isOnline No Bool If true will return online events
ageFriendly No Bool If true will return age friendly events
isFree No Bool If true will return free admission events
minAge No Int Minimum age to attend event
maxAge No Int Maximum age to attend event
lat No – Must be used with lng Double When lat and lng coordinates are used it will order the event results nearest to furthest from the coords set
lng No – Must be used with lat Double When lat and lng coordinates are used it will order the event results nearest to furthest from the coords set
distance No – Must be used with lat and lng Int Filters results by max distance in meters away from the lat lng coords
artForm No String Can be one of the following - film, circus, literary, dance, music, theatre, art

Event field definitions

Fields in bold are always present. All others are optional and may be null or empty.

Access link: https://familyarts.sleeptwitch.com/api/events?token=[add token here]

Property Data Type Description
ID String Fantastic for Families event ID number
Title String Title of event
PermaLink String Full URL of the event on the Fantastic for Families website
Organisation String Full name of the organisation
OrgPermaLink String Full URL of the organisation's profile on Fantastic for Families website
OrgWebsite String Full URL of the organisation's website
BookingLink String Full URL of the event website
Venue String Full name of the event venue
Address1 String Venue address line one
Address2 String Venue address line two
Town String Venue address town
Postcode String Venue address postcode
Phone String Contact phone number
Email String Contact email address
Html String Full HTML event description
ImgLarge String Full URL of large event image
ImgThumb String Full URL of event thumbnail image
MaxCost Decimal Maximum cost of entry (£)
MinCost Decimal Minimum cost of entry (£)
Lng Double Longditude coordinate of event venue if available, otherwise will display the organisation's value.
Lat Double Latitude coordinate of event venue if available, otherwise will display the organisation's value.
MinYear Int Minimum age of entry
MaxYear Int Maximum age of entry
AgeFriendly Bool If true, event is marked as 'Age Friendly'. These are events designed for families with older members
IsOnline Bool If the event is an online event
IsFree Bool If true, entry is free
IsSoldOut Bool If true, event is sold out
IsTicketed Bool If true, event is ticketed
EntryDate DateTime Date and time the event was entered on the Fantastic for Families website
LastUpdated DateTime Date and time the event was last updated on the Fantastic for Families website
StartDate DateTime Start date and time of event
EndDate DateTime End date and time of event
Genres String The type of art form the event has been marked as (e.g. Dance, Film, Theatre)

Organisation field definitions

Fields in bold are always present. All others are optional and may be null or empty.

Access link: https://familyarts.sleeptwitch.com/api/organisations?token=[add token here]

Property Data Type Description
ID String Fantastic for Families organisation ID number
Title String Title of event
PermaLink String Full URL of the organisation profile on the Fantastic for Families website
OrgWebsite String Full URL of the organisation's website
Address1 String Organisation address line one
Address2 String Organisation address line two
Town String Organisation address town
Postcode String Organisation address postcode
Phone String Contact phone number
Email String Contact email address
Html String Full HTML organisation description
ImgLarge String Full URL of large organisation image
ImgThumb String Full URL of organisation thumbnail image
Lng Double Longditude coordinate of organisation
Lat Double Latitude coordinate of organisation
IsVenue Bool If true, organisation is marked as a 'Venue'
EntryDate DateTime Date and time the organisation was entered on the Fantastic for Families website
LastUpdated DateTime Date and time the organisation was last updated on the Fantastic for Families website

Home activity field definitions

Fields in bold are always present. All others are optional and may be null or empty.

Access link: https://familyarts.sleeptwitch.com/api/home-activities?token=[add token here]

Property Data Type Description
ID String Fantastic for Families activity ID number
Title String Title of event
PermaLink String Full URL of the activity on the Fantastic for Families website
Organisation String Full name of the organisation
OrgPermaLink String Full URL of the organisation's profile on Fantastic for Families website
OrgWebsite String Full URL of the organisation's website
ReadMoreLink String Full URL of the 'Read more' link associated to the activity
Phone String Contact phone number
Email String Contact email address
Html String Full HTML activity description
Contact String Fantastic for Families contact email address
Address1 String Organisation address line one
Address2 String Organisation address line two
Town String Organisation address town
Postcode String Organisation address postcode
ImgLarge String Full URL of large activity image
ImgThumb String Full URL of thumbnail activity image
MaxCost Decimal Maximum cost for activity (£)
MinCost Decimal Minimum cost for activity (£)
MinYear Int Minimum recommended age for activity
MaxYear Int Maximum recommended age for activity
Lng Double Longditude coordinate of organisation
Lat Double Latitude coordinate of organisation
AgeFriendly Bool If true, activity is marked as 'Age Friendly'. These are activites designed for families with older members
EntryDate DateTime Date and time the activity was entered on the Fantastic for Families website
LastUpdated DateTime Date and time the activity was last updated on the Fantastic for Families website
Genres String The type of art form the activity has been marked as (e.g. Dance, Film, Theatre)

Our
Fantastic
Partners

Classic FM
Netmums
WhatsOnStage
Fun Kids
Recommended
In Your Area
Seesaw
UKTW
Age Of Creativity
Circus 250
Littlebird
The List
Get Creative
Arts Award
Theatre Tokens
Where Can We Go
London Theatre

Sign up for Fantastic For Families news (managed by the Albany)

Sign up here!

Sign up for Fantastic For Families news (managed by the Albany)