Events API Documentation Event Responses Events Search Request Events-Geo-Request

Events API Documentation

The API is now publishing local authority events, as published by MapAlerter Councils. The data is available as XML, JSON and JSONP to allow you to embed our Events data into your application. The API query structure is very similar to the default Alerts API query results, with a sample XML result as follows:

This is an example of an XML response:
<mapalerterevent>
<entry>
<Event_ID>661</Event_ID>
<Event_GUID>3jd678s0o8hF2Te6nB4aU82lIt4Sx47G</Event_GUID>
<Event_Day>24</Event_Day>
<Event_Month>07</Event_Month>
<Event_Year>2013</Event_Year>
<Event_Hour>09</Event_Hour>
<Event_Minute>00</Event_Minute>
<Event_Title>Book launch at Carlow Museum</Event_Title>
<Event_Description>Joe Bloggs will be launching his new book, etc, etc. This section can include as much HTML as is required. There is no content length restriction here.</Event_Description>
<Event_Category>Culture</Event_Category>
<Venue_Name>Carlow Museum</Venue_Name>
<Venue_Lat>52.12345</Venue_Lat>
<Venue_Lng>-7.54321</Venue_Lng>
<Venue_Distance>10000</Venue_Distance>

If you have any feedback on our API then please let us know. We are happy to extend our API to suit the needs of the developer community in any way we can. There is an API limit request that is currently set at 25000 requests per day. You must register for a free API key in order to use our API. The API is currently in Beta and is subject to some changes and improvements over time. All registered API account holders will be notified if anything changes with the request structures/responses.

Event Responses

The same data fields are returned for each successful API request (Search and Geo). The following is a breakdown of the data fields that are returned for each successful Events API request:

This is an example of an XML response:
<mapalerterevent><entry>
<Event_ID>661</Event_ID>
<Event_GUID>f7466a1828b8296f7f27eda4d569e744</Event_GUID>
<Event_Day>23</Event_Day>
<Event_Month>07</Event_Month>
<Event_Year>2013</Event_Year>
<Event_Hour>14</Event_Hour>
<Event_Minute>30</Event_Minute>
<Event_Title>Book launch and signing at Carlow Library</Event_Title>
<Event_Description>Full details HTML goes here, including links back to website, etc. Use as much HTML code as you like here.</Event_Description>
<Event_Category>Culture</Event_Category>
<Venue_Name>52.8362024000</Venue_Name>
<Venue_Lat>52.8362024000</Venue_Lat>
<Venue_Lng>-6.9091159000</Venue_Lng>
<Issued_By>Carlow Local Authorities</Issued_By>
<Venue_Distance>1000</Venue_Distance>
</entry>
</mapalerterevent>

The following outlines each response field:

File Name type Description
Event_ID int Unique ID for each event that is published on the website.
Event_GUID text This is a global UID. Useful if you are using this data to create feeds
Event_Day text Two-Digit day of the Month (Range: 01-31)
Event_Month text Two-Digit month of the year (Range: 01-12)
Event_Year text Four-Digit Year (eg, 2013, 2014, etc)
Event_Hour text Start Date of the Event as a 24-Hour 2-digit value (Range: 00-23)
Event_Minute float Start Minute of the event as a 2-digit value (Range: 00-59)
Event_Title text The event title, max length is 100 characters.
Event_Description text The event description where HTML code is parsed cleanly
Venue_Name text The venue name
Venue_Lat float The Venue latitude value (eg 53.12345)
Venue_Lng float The Venue longitude value (eg -7.12345)
Issued_By text The local authority who issued this event. Useful for filtering events from certain Councils.
Venue_Distance float This is only delivered as part of the eventgeo API result and refers to the direct distance between the search coordinates (lat & lng) with the venue location in metres (eg, 1000)


Events Search Request

task=eventsearch

The eventsearch API Request allow developers and applications to access the latest events published by local authorities on MapAlerter.com by using a number of filters and search parameters. Along with the compulsory parameters (eg API Key), there are also a series of parameters that are specific to the Events Search Query. 

Parameter Usage Example Required
council

Used to filter a local authority

  • Carlow
  • Limerick
  • Waterford
  • Wexford
  • Roscommon
&council=carlow No
searchterm You can filter your search to return certain keywords from the event's Title and Description &searchterm=party No
category

You can filter your search to return events from specific categories: Options include:

  • Culture
  • Historical
  • Library
  • Music
  • Sports
  • Theatre
&category=music No

Using the required parameters, the following makes up a typical Search API Request:

As you may notice, the various parameters are all optional. it is therefore possible to return the most recent 20 API results by simply omitting the three parameters above.



Events-Geo-Request

task=eventgeo

The "eventgeo" API Request allow developers and applications to access the latest events published by local authorities on MapAlerter.com with results filtered to geographic location. Along with the compulsory parameters (eg API Key), there are also a series of parameters that are specific to the Geo Query.

The method here involves comparing a point location from the URL request and buffering it to create a circular area of interest. If any MapAlerter events exist within this "boundary" then it will be returned as a result. The query result for each alert will be based on the centre point of the event boundary.

Parameter Usage Example Required
latitude

Used to carry out a geo-query based on passed coordinates. These will be compared to the centre-point of the event buffered boundary. Unit is decimal degrees and the projection is WGS84.

&latitude=53.4567 Yes
longitude Used to carry out a geo-query based on passed coordinates. These will be compared to the centre-point of the event buffered boundary. Unit is decimal degrees and the projection is WGS84. &longitude=-7.6543 Yes
buffer This is based in metres and creates a circle in  metres around the passed coordinates from above.  &buffer=25 Yes

Using the required parameters, the following makes up a typical eventgeo API Request:

This query would return events from a (lat,lng) coordinate pair and filter results within 2000 metres.