Should I cycle: designing my API

Once I had determined I was going to use London Air API and OpenWeatherMap’s API it made it easy to design my own API.

I find that documenting this process is essential as otherwise I would forget the decisions I’d made during planning and investigation when it came time to actually write the code.

Should I Cycle API

Document version

Date Version Author Comments
25 August 2014 0.1 Matt Frear Initial version

Cycle endpoint

GET

/v1/cycle?location=London,uk&airquality=wa7,wa9

Arguments

Name Type Required Description
location string 1 The location for weather results.

e.g. London,uk

We will call OpenWeatherMap’s forecast service with this info http://api.openweathermap.org/data/2.5/forecast?
q=London,uk&units=metric

airquality string 0..n A site code to check for pollution.

This parameter can be passed as a comma-separated list to check multiple sites, e.g.

/v1/cycle?location=london&airquality=wa7,wa6
We will call London Air’s API for each location.

A list of available locations is at:

http://api.erg.kcl.ac.uk/AirQuality/Information/Monito
ringSites/GroupName=London/Json
e.g. Putney’s is WA7.

We will call:

http://api.erg.kcl.ac.uk/AirQuality/Hourly/
MonitoringIndex/SiteCode=WA7/Json

Response

The response format will be JSON.

Name Type Description
city string The name of the City
temp int Temperature in degrees Celcius
symbol int OpenWeatherMap’s symbol for the current condition
windDegree int The wind direction in degrees from 0 to 359
windDirection string The 3 digit code for the wind direction, e.g. ENE
windSpeed int The wind speed in m/s
windStrength string A text description for the wind speed, e.g. “Moderate breeze”
pollution [] An array of pollution readings for each sensor requested

A pollution reading looks like

Name Type Description
name string The Sitecode requested, e.g. WA7
speciesCode string The type of reading, e.g. NO2
airQualityIndex int The level of pollution, where 1 = low and 10 = high

The API document is hosted in Google Docs over here: Should I Cycle API.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s