API Reference - Location

Location

Widget

Return metadata for a location based event widget. This metadata contains JSON Link Data, location data and a URL for the corresponding hub page on Ents24. It does not include the actual paged event data, which must be requested seperately from the location/widget-page endpoint.

The location/widget and location/widget-page endpoints return the data used to construct the Ents24 Local Events Widget which can be found here. Custom implementations of the Local Events Widget written using these endpoints are free to parse and present the data as they wish but should do so while adhering to the API Terms of Use which includes a requirement to embed the provided JSON Link Data somewhere in the body of the page on which the widget is included.

Location Widget Metadata
GET/location/widget?location={location}&radius_distance={radius_distance}&distance_unit={distance_unit}&genres={genres}&encode={encode}

Example URI

GET https://api.ents24.com/location/widget?location=geo:54.974384411995,-1.6015806376512&radius_distance=10&distance_unit=mi&genres=["rock","blues"]&encode=utf-8
URI Parameters
HideShow
location
string (required) Example: geo:54.974384411995,-1.6015806376512

The location of events you want a listing for. Values should be prefixed with the type of location data you are submitting [name:, postcode:, geo:]. NB: Values applied to this parameter with the name may be ambiguous E.G: Newcastle. Use location/search endpoint to find a unique location identifier (postcode or lat,lng) that matches the location you want.

radius_distance
integer (optional) Example: 10

The furthest distance from the location you want events listed for.

distance_unit
string (optional) Example: mi

The unit of measurment that should be applied to the radius distance value [mi, km].

genres
string (optional) Example: ["rock","blues"]

A serialised JSON array of genres you want events listed for.

encode
string (optional) Example: utf-8

The character encoding for the data response.

Response  200
HideShow
Headers
Content-Type: application/json
Date: Tue, 26 Aug 2014 08:00:00 GMT
Expires: Tue, 26 Aug 2014 09:00:00 GMT
Body
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Location Widget Metadata",
  "description": "Metadata wrapper for an Ents24 location event widget",
  "type": "object",
  "properties": {
    "jsonLD": {
      "description": "Schema.org linked-data formatted event listings",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "@context": {
            "description": "The context in which the event data is being described (Schema.org)",
            "type": "string"
          },
          "@type": {
            "description": "The type of event the object represents",
            "type": "string"
          },
          "name": {
            "description": "The name of the event. This is shown in the rich snippet. See specific policies about event names below",
            "type": "string"
          },
          "url": {
            "description": "A link to the event's details page",
            "type": "string"
          },
          "startDate": {
            "description": "The starting date and time of the event (ISO8601)",
            "type": "string"
          },
          "endDate": {
            "description": "The ending date and time of the event (ISO8601)",
            "type": "string"
          },
          "eventStatus": {
            "description": "An eventStatus of an event represents its status; particularly useful when an event is cancelled or rescheduled",
            "type": "string"
          },
          "location": {
            "description": "The location of the event",
            "type": "object",
            "properties": {
              "@type": {
                "description": "The type of location",
                "type": "string"
              },
              "name": {
                "description": "The name of the location",
                "type": "string"
              },
              "address": {
                "description": "Physical/Mailing address of the location",
                "type": "object",
                "properties": {
                  "@type": {
                    "description": "The type of address",
                    "type": "string"
                  },
                  "streetAddress": {
                    "description": "The street address",
                    "type": "string"
                  },
                  "addressLocality": {
                    "description": "  The locality. For example, Mountain View.",
                    "type": "string"
                  },
                  "addressRegion": {
                    "description": "The region. For example, CA.",
                    "type": "string"
                  },
                  "postalCode": {
                    "description": "The postal code. For example, 94043.",
                    "type": "string"
                  },
                  "addressCountry": {
                    "description": "The country. For example, USA or ISO 3166-1 alpha-2 country code.",
                    "type": "string"
                  }
                }
              },
              "offers": {
                "description": " An offer to buy tickets for this event",
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "@type": {
                      "description": "The type of offer",
                      "type": "string"
                    },
                    "category": {
                      "description": "A category for the offer",
                      "type": "string"
                    },
                    "price": {
                      "description": "The offer price of a product",
                      "type": "string"
                    },
                    "priceCurrency": {
                      "description": "The currency (in 3-letter ISO 4217 format) of the price",
                      "type": "string"
                    },
                    "availability": {
                      "description": "The availability of the offer",
                      "type": "string"
                    },
                    "validFrom": {
                      "description": "The date when the offer becomes valid",
                      "type": "string"
                    },
                    "validThrough": {
                      "description": "The end of the validity of offer",
                      "type": "string"
                    },
                    "url": {
                      "description": "URL of the offer",
                      "type": "string"
                    }
                  }
                }
              },
              "image": {
                "description": "The URL for the image for this event",
                "type": "string"
              }
            }
          }
        }
      }
    },
    "data": {
      "description": "Location widget metadata",
      "type": "object",
      "properties": {
        "location": {
          "description": "Location of event listing",
          "type": "object",
          "properties": {
            "name": {
              "description": "Place name of location",
              "type": "string"
            },
            "county": {
              "description": "County name",
              "type": "string"
            },
            "latitude": {
              "description": "Latitude of location",
              "type": "float"
            },
            "longitude": {
              "description": "Longitude of location",
              "type": "float"
            }
          }
        },
        "web-link": {
          "description": "Link to the corresponding hub page on Ents24",
          "type": "string"
        }
      }
    }
  }
}

Widget Page

Return location based, paged events data for a widget. These paged listings are grouped by date and returned in date order. The response does not contain the other metadata needed for the widget which must be requested seperately from the location/widget endpoint.

The location/widget and location/widget-page endpoints return the data used to construct the Ents24 Local Events Widget which can be found here. Custom implementations of the Local Events Widget written using these endpoints are free to parse and present the data as they wish but should do so while adhering to the API API Terms of Use which includes a requirement to embed the provided JSON Link Data somewhere in the body of the page on which the widget is included.

Location Widget Page
GET/location/widget-page?location={location}&radius_distance={radius_distance}&distance_unit={distance_unit}&genres={genres}&encode={encode}&results_per_page={results_per_page}&page={page}

Example URI

GET https://api.ents24.com/location/widget-page?location=geo:54.974384411995,-1.6015806376512&radius_distance=10&distance_unit=mi&genres=["rock","blues"]&encode=utf-8&results_per_page=25&page=1
URI Parameters
HideShow
location
string (required) Example: geo:54.974384411995,-1.6015806376512

The location of events you want a listing for. Values should be prefixed with the type of location data you are submitting [name:, postcode:, geo:] NB: Values applied to this parameter with the name may be ambiguous E.G: Newcastle. Use location/search endpoint to find a unique location identifier (postcode or lat,lng) that matches the location you want

radius_distance
integer (optional) Example: 10

The furthest distance from the location you want events listed for

distance_unit
string (optional) Example: mi

The unit of measurment that should be applied to the radius distance value [mi, km]

genres
string (optional) Example: ["rock","blues"]

A serialised JSON array of genres you want events listed for

encode
string (optional) Example: utf-8

The character encoding for the data response

results_per_page
integer (optional) Example: 25

The number of results you want per page/chunk [5, 10, 25, 50, 75, 100]

page
integer (optional) Example: 1

The page/chunk of results to be requested

Response  200
HideShow
Headers
Content-Type: application/json
Date: Tue, 26 Aug 2014 08:00:00 GMT
Expires: Tue, 26 Aug 2014 09:00:00 GMT
X-Next-Page: R2U=
X-Previous-Page: bUw=
X-Total-Items-Found: 75
Body
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Location Widget Page",
  "description": "Paged event data for an Ents24 location event widget",
  "type": "object",
  "properties": {
    "listings": {
      "description": "Event listings for location grouped by date",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "description": "RFC-3339 formatted date for listing section",
            "type": "string"
          },
          "events": {
            "description": "Event listings for location on given date",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "description": "Title of event",
                  "type": "string"
                },
                "eventUrl": {
                  "description": "URL for event page",
                  "type": "string"
                },
                "isFree": {
                  "description": "Flag for if event is free",
                  "type": "boolean"
                },
                "status": {
                  "description": "Event status (sold out or not)",
                  "type": "string"
                },
                "venueName": {
                  "description": "Name of venue",
                  "type": "string"
                },
                "venueTown": {
                  "description": "Name of venue town",
                  "type": "string"
                },
                "ticketUrl": {
                  "description": "URL for tickets",
                  "type": "string"
                },
                "image": {
                  "description": "Image for event",
                  "type": "string"
                },
                "trackUrl": {
                  "description": "URL to track event",
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}