Introduction Requirements Search-Request Geo-Request Responses

Introduction

Welcome to Version 1 of the MapAlerter.com API. The aim of our API is to allow developers to access our alert data through their own applications such as Mobille Apps, widgets and many more. We provide our data as XML, JSON and JSONP to reflect our belief in Open Data. Data is retrieved by sending a HTTP(S) GET request to a URL with a required API key, the response format, a task parameter, and query parameter(s).

The API is delivered as a series of GET requests with various parameters allowing you to only access the information that interests you and your audience. For example, you can refine our alert data so that it will only include results from Wexford County Council. Similarly you can refine results to only include Flood Alerts and Severe Weather Warnings if you are interested in consuming our data for a severe weather alert system.

All alerts posted on MapAlerter include geographic information. We are happy to share our GIS boundaries and layer information in a structured manner such as a delimited list of coordinates. For ease of use we also post the number of coordinates per alert boundary.

Our documentation is listed below and is straightforward to follow. We use a neat coloured structure when we include examples of how the API in action, for example:

This is an example of an XML response:
<mapalert><entry>
<id>661</id>
<title>Water Interruption Notice - Thurs 30th Aug 2012</title>
<created_by>2703</created_by>
<SMS>Water Interruption Notice 3pm-6pm Thurs 30th Aug 2012 Askea Area, Carlow</SMS>
<category>water</category>
<latitude>52.8362024000</latitude>
<longitude>-6.9091159000</longitude>
<coordstring>-6.9091,52.8362024;-6.90917,52.83561;-6.90934,52.83501;</coordstring>
<coordcount>3</coordcount>
<Day>29</Day>
<Month>8</Month>
<Year>2012</Year>
<Hour>15</Hour>
<Minute>21</Minute>
<bitly>http://bit.ly/N3KQFx</bitly>
</entry>
</mapalert>

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.

Requirements

1. Base URL

The MapAlerter API is located at the following base URL:

https://api.mapalerter.com/component/api

Therefore all requests to the MapAlerter API must go through this base URL.


2. Select a Task

Like any API, it is necessary to outline the request using the following URL parameter:

https://api.mapalerter.com/component/api?task=<TaskName>

There are currently 2 API GET requests that can be made:

  • task=search
  • task=geo

Example:

https://api.mapalerter.com/component/api?task=search
https://api.mapalerter.com/component/api?task=geo

3. Pass an API Key

It is necessary to pass an API key for all requests. You can register for a free MapAlerter API account which will entitle you to 25000 requests per day. The API key is passed as a compulsory parameter in all API requests as follows:

https://api.mapalerter.com/component/api?key=<API-KEY>

Example:

https://api.mapalerter.com/component/api?key=dec418c88da994717af72a851d21e980

4. Response Format

The API returns results in XML, JSON or JSONP and the preferred format should be specified. If not format is specified then the request will default to XML.

https://api.mapalerter.com/component/api?format=<RESPONSE-FORMAT>

Example:

https://api.mapalerter.com/component/api?format=xml

5. Overview of a simple API request

Putting the above 4 points into a single structure, the following represents the basic requirements for any API request

https://api.mapalerter.com/component/api?key=<API-KEY>&task=<TaskName>&format=<RESPONSE-FORMAT>

Example:

https://api.mapalerter.com/component/api?key=dec418c88da994717af72a851d21e980&task=geo&format=xml

Individual API requests also have compulsory parameters. For example, the "Geo-Query" is based on a location search, so coordinates are required in the API request. However these are not required in the basic search API task.



6. Callback Parameter (only required for JSONP)

An additional parameter is required if you intend on consuming alert data using JSONP

https://api.mapalerter.com/component/api?key=<API-KEY>&task=<TaskName>&format=jsonp&callback=?

Example:

https://api.mapalerter.com/component/api?key=dec418c88da994717af72a851d21e980&task=geo&format=jsonp&callback=?

This callback parameter is not required for JSON or XML.

Search-Request

task=search

The Search API Request allow developers and applications to access the latest alerts published by local authorities on MapAlerter.com. Along with the compulsory parameters outlined above, there are also a series of parameters that are specific to the Search Query. 

Parameter Usage Example Required
alerter

Used to filter a local authority by a unique code

  • 79 = Limerick County Council
  • 88 = Roscommon County Council
  • 92 = Waterford City Council
  • 95 = Wexford County Council
  • 2703 = Carlow County Council
&alerter=88 No
searchterm You can filter your search to return certain keywords from the alert's Title, SMS content and Description &searchterm=water No
category

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

  • Road (Road Work Alerts, Incidents and Accidents)
  • Bridge (Bridge Lifts for Waterford City)
  • Community (Community Alerts can be for parades or other general notices)
  • Severe (Severe Weather Warnings)
  • Water (Water Service Disruptions & Boil Water Notices)
&category=severe No

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

Geo-Request

task=geo

The GeoAPI Request allow developers and applications to access the latest alerts published by local authorities on MapAlerter.com with results filtered to geographic location. Along with the compulsory parameters outlined above, 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 activity exists 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 alert 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 alert 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 alert boundary.  Unit is decimal degrees and the projection is WGS84. &longitude=-7.6543 Yes
buffer This is based in kilometres and creates a circle in  kilometres   around the passed coordinates from above.  &buffer=25 Yes

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

This query would return results from a (lat,lng) coordinate pair and filter results within 25 kilometres.

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:

This is an example of an XML response:
<mapalert><entry>
<id>661</id>
<title>Water Interruption Notice - Thurs 30th Aug 2012</title>
<created_by>2703</created_by>
<SMS>Water Interruption Notice 3pm-6pm Thurs 30th Aug 2012 Askea Area, Carlow</SMS>
<category>water</category>
<latitude>52.8362024000</latitude>
<longitude>-6.9091159000</longitude>
<coordstring>-6.90911,52.8362;-6.90919,52.8356;-6.9093,52.835;</coordstring>
<coordcount>3</coordcount>
<Day>29</Day>
<Month>8</Month>
<Year>2012</Year>
<Hour>15</Hour>
<Minute>21</Minute>
<bitly>http://bit.ly/N3KQFx</bitly>
</entry>
</mapalert>

The following outlines each response field:

File Name type Description
id int Unique ID for each alert that is published on the website. If you want to link back to an alert published on MapAlerter.com then use the example structure: http://www.mapalerter.com/alerts/viewtrack/123--.html (where 123 is the id)
title text This is a basic introduction used by local authorities to describe the alert.
description text MapAlerter allows Councils to issue alerts via email, and this can include a large amount of HTML. Whatever is input as an "Email Alert" will be published to the Description
created_by int The codes used here refer to the various local authorities using MapAlerter. The codes are outlined in the above "Search-Request" section.:
SMS text The original content that was published on MapAlerter for the SMS Text Alert content
category text MapAlerter issues alerts into specific categories. So if your app is focused on Flooding, then only consume our "Flood" categories.
latitude float Latitude Coordinate for a MapAlert. The WGS 84 projection is used to coincide with Google/OpenLayers applications. This refers to the latitude value for the centre point of the Map Alert.
longitude float Longitude Coordinate for a MapAlert. The WGS 84 projection is used to coincide with Google/OpenLayers applications. This refers to the longitude value for the centre point of the Map Alert.
coordstring text A delimited string of coordinates that make up the boundary for an alert. You can merge these back up to form a polygon using your own GIS or Web skills!
coordcount int If it helps, use our coordinate counter to help you form polygons from the delimited string. The coordcount field will allow your application to determine how many coordinates exist on the polygon thast needs to be created.
Day, Month, Year, Hour, Minute int The date breakdown will allow you to search by date filter and to parse the results in a way that suits your application. For example, use a string replacer to help formulate the date into an RSS-compliant field, etc.
bitly text A shortened URL that links to the correct alert page on MapAlerter.com. Useful for integration with social media applications.