Days Out Guide API v1 (20180614)

Rail Delivery Group
Days Out Guide API
Version 1.0
14th June 2018
Page 1
Contents
Contents 2
Overview 5
Features 5
All data from daysoutguide.co.uk available 5
Updated system for assigning IDs 5
Powerful filtering of attraction results 5
Integrate into a white labelled solution 5
In-built image cropping and resizing 5
Performance and stability 5
Days Out Guide “XML Feed” 5
API endpoints 7
Get attractions endpoint 7
Request parameters 7
Example request 8
Response object fields 8
Sample JSON response 9
Get attraction by ID endpoint 10
Example request 11
Get offers by attraction ID endpoint 13
Example request 13
Get offer by ID endpoint 14
Example request 14
Page 2
Claim offer for attraction ID endpoint 15
Example request 15
Get categories endpoint 16
Example request 16
Get genres endpoint 17
Example request 17
Get regions endpoint 18
Example request 18
Get train stations endpoint 19
Example request 19
Authorisation 20
Request headers 20
Generating an access token 20
Request parameters 20
Example request 20
Example JSON response 21
Handling expired tokens 21
Invalid token error 21
Page 3
Image resizing 22
URL parameters 22
Example request 22
Revision history 23

Page 4
Overview
The purpose of the Days Out Guide API is to allow partners to display a feed of attractions and offers within
their own systems, and claim offers / vouchers from the Days Out Guide system.
The API exposes all of the data used by daysoutguide.co.uk via a RESTful web API available in both JSON
and XML formats.
Permissions as to what data a given API user can access is defined when their API credentials are issued.
Features
All data from daysoutguide.co.uk available
Unlike the current “XML Feed” that only surfaces limited attraction data, the Days Out Guide API serves all
of the attraction and offers data that exists within the system. The API is even used within the Days Out
Guide site so it can be trusted as the source of truth for data.
Updated system for assigning IDs
A new system for IDs has been introduced to ensure the IDs associated with data in the system (e.g.
attractions, offers, train stations, etc) remain unique. Everything in the system has been assigned a unique
Guid based ID. Train stations now respond to their National Rail CRS station codes as their unique IDs.
An up-to-date list of CRS codes can be found via National Rail:

http://www.nationalrail.co.uk/stations_destinations/48541.aspx
Powerful filtering of attraction results
It is possible to filter the wide range of attractions on offer through Days Out Guide by a wide range of
parameters, including by multiple categories, genres and regions.
Integrate into a white labelled solution
The ability to redeem vouchers / coupons via the API makes it simple to integrate Days Out Guide’s rich
variety of offers into a white labelled solution presented through your own website.
In-built image cropping and resizing
All images served by the API are able to be cropped and resized to fit the specific needs for your use case.
Performance and stability
The Days Out Guide API was built with performance and stability in mind as a more suitable alternative to
the current “XML Feed”. The API sits on separate high-availability infrastructure from the daysoutguide.co.uk
website to ensure the service is always available and requests are responded to quickly.
Days Out Guide “XML Feed”

NOTE: The new Days Out Guide API is intended to replace use of the “XML Feed” functionality that has
historically been used to retrieve data about the attractions available in the Days Out Guide system. The
Page 5
“XML Feed” functionality is now considered deprecated and the Days Out Guide API should be used in its
place. Essential fixes to ensure the “XML Feed” performs as expected will be applied, but new features and
improvements will not be added going forward.
Page 6
API endpoints
There are 9 different endpoints on the API to retrieve data and perform transactions within the Days Out
Guide system.
● Get attractions - /attractions

● Get attraction by ID - /attractions/{attractionId}
● Get offers by attraction ID - /attractions/{attractionId}/offers
● Get offer by ID - /offers/{offerId}
● Claim offer for attraction ID - /offers/{offerId}/claim/{attractionId}
● Get categories - /taxonomy/categories
● Get genres - /taxonomy/genres
● Get regions - /taxonomy/regions
● Get train stations - /taxonomy/stations
The API is served over HTTPS and is available through a public domain https://api.daysoutguide.co.uk/.
API calls are versioned (e.g. /api/v1/attractions) to allow changes to be easily rolled out without breaking
existing implementations. Friendly meaningful error messages with corresponding HTTP status codes are
returned where necessary.
Data is available in both JSON and XML formats determined by the “Accept” or “Content-Type” headers sent
with each request, as per HTTP Content Negotiation standards. See
https://docs.microsoft.com/en-us/aspnet/web-api/overview/formats-and-model-binding/content-negotiation
for more information on Content Negotiation.
Get attractions endpoint

The /attractions endpoint returns a collection of all attractions in the Days Out Guide system that have been
made available.
It is possible to filter and sort the collection of results returned by the API. By default there are no filters set.
Results appear in order of most popular (defined by the number of vouchers claimed).
Request parameters
Parameter Description Validation rules
Page The current page of results Optional, maximum value

of 100
PerPage The number of results to return per page Optional, defaults to 10 if

Page is set
OrderBy Order the results set by Defaults to most popular

● Popular
● A-Z
● Z-A
● Recent
● Ending
Page 7
Region Filters the results set to only return Accepts a pipe “|”
attractions within a given region; e.g. separated list to filter by
London, attractions where one or
Scotland, South West more of the given regions
is set
Category Filters the results set to only return Accepts a pipe “|”
attractions within a given category; e.g. separated list to filter by
Theme & Adventure Parks, Galleries & attractions where one or
Museums more of the given
categories is set
Genre Filters the results set to only return Accepts a pipe “|”
attractions within a given genre; e.g. Under separated list to filter by
£10, Families and Children attractions where all of
the given genres is set
ShowFree Include “Free” and “Information” attractions Defaults to false

in results
Example request
https://api.daysoutguide.co.uk/v1/attractions?region=London|Scotland&genre=Free|Families and
Children&showFree=true&orderBy=recent
Response object fields
Field name Description Type
Id Attraction Id Guid (string)
Name Name of the attraction string
Description Description of the attraction string
Directions Directions to the attraction string
PhoneNumber Phone number of the attraction string
Website URL for the attraction string
PostCode Postcode of the attraction string
Categories Attraction type object
Genres Attraction genre object
FeaturedImage URL for the main attraction image string
Images URLs for images of the attraction array
Region List of the regions the attraction is located array
Page 8
within
NearestStation Name of the nearest station object
AccessInformation Reference to attractions own accessibility string

information
OpeningTimes Details about when the offer applies which is string

generally when the same as the opening
times
Admission The prices that the offer applies to object
RecommendAttractions List of Attraction IDs for attractions located object

close to or similar to the listed attraction,
maximum of 5
Offers List of Offers for offers associated with object

the listed attraction, including details
about the offer
Sample JSON response
{
“Items”: [{
"Id": "1fa8e7cb-0366-466e-b6aa-63b6654840b1",
"Name": "The Coca-Cola London Eye",
"Description": "The Coca-Cola London Eye has been London’s number one visitor experience for
over a decade. Step into a capsule and feel the exhilaration as you rise up over the River Thames and come
face to face with the Houses of Parliament and Big Ben, before soaring above them, up to 135 metres on the
world’s tallest cantilevered observation wheel.A trip on the Coca-Cola London Eye undoubtedly
makes up part of the ultimate day out in the city and is ideally located on the beautiful Southbank amongst
brilliant bars and restaurants.Included with every ticket is the Coca-Cola London Eye 4D Cinema
Experience. This heart-warming mini-movie is a must-see for any Londoner and comes with a few surprises
and a great soundtrack featuring Coldplay and Goldfrapp. It creates the perfect build up to your
take-off.",
"Directions": "Exit the M4 at Junction 1",
"PhoneNumber": "03333212001",
"Website": "https://www.londoneye.com/",
"PostCode": "SE1 7PB",
"Categories": [{
"Id": "9c809ece-12b4-4122-a3c9-3837a58406bd",
"Name": "Tours & Guided Walks"
},{
"Id": "6b818e92-05fc-4c87-aad4-38bd62872c34",
"Name": "Landmarks & Historical Sites"
}],
"Genres": [{
"Id": "4d21cc5b-fa3a-43fe-b45d-365b0db54592",
"Name": "Family And Children"
},{
Page 9
"Id": "a1c1bc7b-756a-4a2d-a00f-c5aeb9239ff9",
"Name": "London"
}],
"FeaturedImage": "https://www.daysoutguide.co.uk/media/1234/london-eye.jpg",
"Images": [
"https://www.daysoutguide.co.uk/media/1234/new-image.jpg",
"https://www.daysoutguide.co.uk/media/1234/alternative-image.jpg"
],
"Region": "London",
"NearestStation": {
"Id": "WAT",
"Name": "London Waterloo"
},
"AccessInformation": "Please check <a href="https://www.website.com/">website</a> for
details.",
"OpeningTimes": "Daily from 10.00",
"Admission": {
"Adult": 24.95,
"Child": 24.95
},
"RecommendAttractions": [
"15ac9a80-abd3-410f-95d0-923940bc3ec2",
"324240e6-4ee9-4798-8580-90a85474d083",
"5303d949-902c-4a46-9e87-1c6883343d85",
"Ede10133-8509-4766-89cf-5884b5617ddc",
"F27a56b8-87e6-4e9e-a0d0-df85b5d676cd"
],
"Offers": [{
"Id": "4fce5728-4c1a-44bf-8311-341ebd8d9f23",
"Name": "2FOR1 London",
"Terms": "Lorem ipsum dolor sit amet, et denique corrumpit splendide nam,",
"OfferType": "2FOR1",
"Expires": 2020-12-31 00:00:00,
"SavingsInfo": "Lorem ipsum dolor sit amet, et denique corrumpit splendide nam,"
},
{
...
}]
},{
...
}],
“TotalItems”: 105,
“ItemsPerPage”: 10
}
Get attraction by ID endpoint

The /attractions/{attractionId} endpoint returns a single attraction from the Days Out Guide system, provided
Page 10
it has been made available to the requesting API user. The object returned by the endpoint will be in the
same structure as a singular result item from the /attractions endpoint - an example of this is below.
There are no request parameters for this endpoint.
Example request
https://api.daysoutguide.co.uk/v1/attractions/1fa8e7cb-0366-466e-b6aa-63b6654840b1
Id Attraction Id Guid (string)
Name Name of the attraction string
Description Description of the attraction string
Directions Directions to the attraction string
PhoneNumber Phone number of the attraction string
Website URL for the attraction string
PostCode Postcode of the attraction string
Categories Attraction type object
Genres Attraction genre object
FeaturedImage URL for the main attraction image string
Images URLs for images of the attraction array
Region List of the regions the attraction is located array

within
NearestStation Name of the nearest station object
AccessInformation Reference to attractions own accessibility string

information
OpeningTimes Details about when the offer applies which is string

generally when the same as the opening
times
Admission The prices that the offer applies to object
RecommendAttractions List of Attraction IDs for attractions located object

close to or similar to the listed attraction,
maximum of 5
Page 11
Offers List of Offers for offers associated with object
the listed attraction, including details
about the offer
{
"Id": "1fa8e7cb-0366-466e-b6aa-63b6654840b1",
"Name": "The Coca-Cola London Eye",
"Description": "The Coca-Cola London Eye has been London’s number one visitor experience for over
a decade. Step into a capsule and feel the exhilaration as you rise up over the River Thames and come face
to face with the Houses of Parliament and Big Ben, before soaring above them, up to 135 metres on the
world’s tallest cantilevered observation wheel.A trip on the Coca-Cola London Eye undoubtedly
makes up part of the ultimate day out in the city and is ideally located on the beautiful Southbank amongst
brilliant bars and restaurants.Included with every ticket is the Coca-Cola London Eye 4D Cinema
Experience. This heart-warming mini-movie is a must-see for any Londoner and comes with a few surprises
and a great soundtrack featuring Coldplay and Goldfrapp. It creates the perfect build up to your
take-off.",
"Directions": "Exit the M4 at Junction 1",
"PhoneNumber": "03333212001",
"Website": "https://www.londoneye.com/",
"PostCode": "SE1 7PB",
"Categories": [{
"Id": "9c809ece-12b4-4122-a3c9-3837a58406bd",
},{
"Id": "6b818e92-05fc-4c87-aad4-38bd62872c34",
"Name": "Landmarks & Historical Sites"
}],
"Genres": [{
},{
"Id": "a1c1bc7b-756a-4a2d-a00f-c5aeb9239ff9",
"Name": "London"
}],
"FeaturedImage": "https://www.daysoutguide.co.uk/media/1234/london-eye.jpg",
"Images": [
"https://www.daysoutguide.co.uk/media/1234/new-image.jpg",
"https://www.daysoutguide.co.uk/media/1234/alternative-image.jpg"
],
"Region": "London",
"NearestStation": {
"Id": "WAT",
"Name": "London Waterloo"
},
"AccessInformation": "Please check <a href="https://www.website.com/">website</a> for
details.",
"OpeningTimes": "Daily from 10.00",
Page 12
"Admission": {
"Adult": 24.95,
"Child": 24.95
},
"RecommendAttractions": [
"15ac9a80-abd3-410f-95d0-923940bc3ec2",
"324240e6-4ee9-4798-8580-90a85474d083",
"5303d949-902c-4a46-9e87-1c6883343d85",
"Ede10133-8509-4766-89cf-5884b5617ddc",
"F27a56b8-87e6-4e9e-a0d0-df85b5d676cd"
],
"Offers": [{
"Id": "4fce5728-4c1a-44bf-8311-341ebd8d9f23",
"Expires": 2020-12-31 00:00:00,
},
{
...
}]
}
Get offers by attraction ID endpoint

The /attractions/{attractionId}/offers endpoint returns a single offer from the Days Out Guide system,
provided it has been made available to the requesting API user. The object returned by the endpoint will be
in the same structure as a singular result item from the /attractions/{attractionId}/offers endpoint - an
example of this is below.
Example request
https://api.daysoutguide.co.uk/v1/attractions/1fa8e7cb-0366-466e-b6aa-63b6654840b1/offers
Id Offer Id Guid (string)
Name Name of the offer string
Terms Terms of the offer string
OfferType Type of the offer; e.g. 2FOR1, 3FOR2, 30% string
Page 13
OFF
Expires Date that the offer expires datetime
SavingsInfo Additional information about the offer that string

needs to be displayed
{
“Items”: [{
"Id": "4fce5728-4c1a-44bf-8311-341ebd8d9f23",
"Expires": 2020-12-31 00:00:00,
},
{
...
}],
}
Get offer by ID endpoint

The /offers/{offerId} endpoint returns a collection of all offers that have been associated to the given
attraction within the Days Out Guide system. It is not possible to retreive future or expired offers from the
API.
Example request
https://api.daysoutguide.co.uk/v1/offers/4fce5728-4c1a-44bf-8311-341ebd8d9f23
Id Offer Id Guid (string)
Page 14
OFF
SavingsInfo Additional information about the offer that string

needs to be displayed
{
“Items”: [{
"Id": "4fce5728-4c1a-44bf-8311-341ebd8d9f23",
"Expires": 2020-12-31 00:00:00,
},
{
...
}],
}
Claim offer for attraction ID endpoint

The /offers/{offerId}/claim/{attractionId} endpoint returns the necessary information needed to claim / redeem
an offer from Days Out Guide. It is not possible to claim / redeem future or expired offers via the API.
Example request
https://api.daysoutguide.co.uk/v1/offers/4fce5728-4c1a-44bf-8311-341ebd8d9f23/claim/1fa8e7cb-0366-466
e-b6aa-63b6654840b1
Id Id for the given offer Guid (string)
Page 15
OFF
VoucherType Type of the voucher; e.g. Days Out Guide, string

Merlin, External
CouponCode Unique coupon code from a third-party string

provided list, when the Voucher Type is
“buy online”
ClaimUrl URL to claim the offer - link to add the string

current attraction and offer to “My Trip” on
daysoutguide.co.uk
Alternatively, this could be an external URL

to a third-party site where the customer
should redeem the offer
{
"Id": "4fce5728-4c1a-44bf-8311-341ebd8d9f23",
"VoucherType": "Days Out Guide",
"Expires": 2020-12-31 00:00:00,
"CouponCode": "",
"ClaimUrl": "https://www.daysoutguide.co.uk/london-eye"
}
Get categories endpoint

The /taxonomy/categories endpoint returns a collection of all categories that exist in the Days Out Guide
system. This endpoint is intended to be used to determine the various filter options that are available for the
/attractions API endpoint.
Example request
https://api.daysoutguide.co.uk/v1/taxonomy/categories
Page 16
Id Category Id Guid (string)
Name Name of the category string
{[
{
"Id": "9c809ece-12b4-4122-a3c9-3837a58406bd",
},
{
...
}
]}
Get genres endpoint

The /taxonomy/genres endpoint returns a collection of all genres that exist in the Days Out Guide system.
This endpoint is intended to be used to determine the various filter options that are available for the
Example request
https://api.daysoutguide.co.uk/v1/taxonomy/genres
Id Genre Id Guid (string)
Name Name of the genre string
{[
{
},
{
...
Page 17
}
]}
Get regions endpoint

The /taxonomy/regions endpoint returns a collection of all regions that exist in the Days Out Guide system.
This endpoint is intended to be used to determine the various filter options that are available for the
Example request
https://api.daysoutguide.co.uk/v1/taxonomy/regions
Id Region Id Guid (string)
Name Name of the region string
Inner Regions Regions within the region, “sub-regions” array

e.g. Scotland has an inner region of East
Scotland
{[
{
"Id": "1c7dde89-526f-4a74-809c-80d68deab80f",
"Name": "London",
“InnerRegions”: [{
"Id": "1c7dde89-526f-4a74-809c-80d68deab80f",
"Name": "London",
“InnerRegions”: [{
...
}]
},
{
...
}]
},
{
...
}
Page 18
]}
Get train stations endpoint

The /taxonomy/stations endpoint returns a collection of all train stations that exist in the Days Out Guide
system.
Example request
https://api.daysoutguide.co.uk/v1/taxonomy/stations
Id Train station CRS code string
Name Name of the train station string
Url URL of the nationalrail.co.uk page about

the train station
{[
{
"Id": "WAT",
"Name": "London Waterloo",
“Url”: “http://ojp.nationalrail.co.uk/service/ldbboard/dep/WAT.aspx”
},
{
...
}
]}
Page 19
Authorisation
The API is protected by a token based authentication system, each access token has a lifespan of 24 hours.
Requests to the API must be sent with an “Authorization” header containing the access token.
Request headers
Header name Value
Authorization “Bearer ACCESS-TOKEN-GOES-HERE”
Generating an access token

To obtain a token you must POST to the /token API endpoint with three parameters. Each request to the
/token API endpoint will generate a new unique access token and automatically force existing access tokens
to be invalid.
Request parameters
Parameter Description Validation rules
grant_type The authorisation grant type Must always be set to

“password”
(For the Days Out Guide API this will always
be “password”)
username The API user’s username
password The API user’s password
Example request
https://api.daysoutguide.co.uk/token?grant_type=password&username=demoUser&password=LxZsWrGV
access_token The access token string
token_type The access token type string

(For the Days Out Guide API this will always
be “bearer”)
expires_in The time in milliseconds until the generated int

access token expires
Page 20
Example JSON response
{
"access_token":
"mLoY8DEiLcjvv4_kS6diTCIieKJA2Hip3xRruJLj8QgOVhaXHsW3MwD3kEF47ARKnWP8n6Q2C4ISf1Wi0tn
Q2FK54N1UXDQBjxp1J6dWqjzLnzhjY7DFc_OSWw09a7cB15orZDc5M5Cv_CF9MuFQ5cHxRWVS7ilMkED
5Z83t7FvWJMRrsUK49rhaJuxKBk2XAnGqo7PkG1lUp1oyDldfRNVCIkHUF2JkK97qyVwkuqddfcuUMzIRuBn
HqCtWqbLxkjRJ5HF7LaEssph4NllV7b6hE5aNb_u36qlNCAkYGOShB-iVhv_ZSzmCziBS2Pmk4wt5iopTLPx
Z3AfG58jkPg",
"token_type": "bearer",
"expires_in": 86399
}
For optimum performance it is recommended to store a copy of your access token within your application
until it expires as the token generation process is intensive and can be slow.
Handling expired tokens

If you make a request to an API endpoint using an invalid or expired token you can expect the following
response from the API:
Invalid token error
{
"message": "Authorization has been denied for this request."
}
In this scenario it is recommended to make an attempt to obtain a new token from the API via the /token
endpoint and retry the original request again. Any further errors experienced after retrying the request should
be handled gracefully by your application rather than continuing to attempt retrying request.
Page 21
Image resizing
The URLs of images returned by the API point to the resource in its original uploaded form without any
optimisations. For optimum performance, images should always be resized to appropriate dimensions for
their purpose. This can be achieved by adding a variety of query string parameters onto the image URLs.
The API relies on the ImageProcessor.NET open-source library to resize images. A full definition of the
available resize modes can be found here
http://imageprocessor.org/imageprocessor-web/imageprocessingmodule/resize/
URL parameters
Parameter name Description Example
Width The desired width of the image width=500
Height The desired height of the image height=500
● Pad
Mode mode=crop
● BoxPad
● Crop Defaults to “pad”
● Min
● Max
● Stretch
Example request
https://www.daysoutguide.co.uk/media/1234/new-image.jpg?mode=crop&width=200&height=200
In this example “new-image.jpg” would be returned but cropped to 200px in height and 200px wide.
In the case that the supplied crop size is larger or not proportionate to the original image dimensions a black
border will fill the empty space around the image.
Page 22
Revision history
From time to time changes are required to the API specification that require this document to be updated.
These are logged in the table below.
Date Description
5th December 2017 Initial release
14th June 2018 Changing separator for Region, Category and Genre filters on
/attractions API endpoint to use pipes “|” rather than commas “,”.
Previously: /attractions?region=London,Scotland
Now: /attractions?region=London|Scotland
Page 23

Sprache

Willkommen bei Scribd!

Days Out Guide API v1 (20180614)

Hochgeladen von

Dokumentinformationen

Beschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Beschreibung:

Copyright:

Verfügbare Formate

Days Out Guide API v1 (20180614)

Originaltitel:

Hochgeladen von

Beschreibung:

Copyright:

Verfügbare Formate

Verwandte Titel

Rail Delivery Group

Days Out Guide API

14th June 2018

All data from daysoutguide.co.uk available 5

Updated system for assigning IDs 5

Powerful filtering of attraction results 5

Integrate into a white labelled solution 5

In-built image cropping and resizing 5

Performance and stability 5

Days Out Guide “XML Feed” 5

Get attractions endpoint 7

Response object fields 8

Sample JSON response 9

Get attraction by ID endpoint 10

Response object fields 11

Sample JSON response 12

Get offers by attraction ID endpoint 13

Response object fields 13

Sample JSON response 14

Get offer by ID endpoint 14

Response object fields 14

Claim offer for attraction ID endpoint 15

Response object fields 15

Sample JSON response 16

Get categories endpoint 16

Response object fields 16

Sample JSON response 17

Get genres endpoint 17

Response object fields 17

Sample JSON response 17

Get regions endpoint 18

Response object fields 18

Sample JSON response 18

Get train stations endpoint 19

Response object fields 19

Sample JSON response 19

Generating an access token 20

Response object fields 20

Example JSON response 21

Handling expired tokens 21

Invalid token error 21

All data from daysoutguide.co.uk available

Updated system for assigning IDs

An up-to-date list of CRS codes can be found via National Rail:

Powerful filtering of attraction results

Integrate into a white labelled solution

In-built image cropping and resizing

Performance and stability

Days Out Guide “XML Feed”

● Get attractions - ​/attractions

Get attractions endpoint

Parameter Description Validation rules

Page The current page of results Optional, maximum value

PerPage The number of results to return per page Optional, defaults to 10 if

OrderBy Order the results set by Defaults to ​most popular

ShowFree Include “Free” and “Information” attractions Defaults to ​false

● Get attractions - /attractions

OrderBy Order the results set by Defaults to most popular

ShowFree Include “Free” and “Information” attractions Defaults to false