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!
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.
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
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
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 |
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 |
| 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) |
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 |
| 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 |
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 |
| 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) |
