API Introduction
The JobsGoLocal API is very simple.
You tell it which offices you would like to see the latest vacancies for, and how you would like the results formatted.
THE NODE
http://api.JobsGoLocal.org.uk/
equivalent to:
http://api.JobsGoLocal.org.uk/index.htm
THE CALL
It accepts a number of GET arguments, only the first one, offices is mandatory.
offices=
Up to 10 pipe ( | ) delineated three letter "Jobcentre Plus" office codes. The codes can be collected up from the map.
format=
[optional] One of either json [default], php, xml or yaml.
callback=
[optional] The Javascript function to be called when it arrives back at the client. When set the payload will be the same as json, but contained within a callback so it will become jsonp.
url=
[optional] Let me know which site you using url=yoursite.com or use url=testing if you are playing around and will be hitting the site more than once per day and I will cut you some slack.
See documentation for each format option to see example calls, code samples, error codes and headers information.
Sample GET call for 2 offices, Guildford [GUF] and Woking [WOA] - returns json by default.
http://api.JobsGoLocal.org.uk/?offices=GUF|WOA
Sample GET call for 1 office, Guildford [GUF] - returning xml;
http://api.JobsGoLocal.org.uk/?offices=GUF&format=xml
FREQUENCY
The data is only updated once a day, at midnight (GMT) from the zois ftp service, so make your call to the API in wee the small hours. Leave it till after 1am and then you don't need worry about daylight saving time changes on any of the servers involved.
You are best leaving out calls on Sunday and Monday morning as there are very few jobs added on the preceding days.
CACHING
As the data is only updated once a day you are strongly advised, like really, I insist, to cache the results on your own servers and do any post-production assembly, filtering or formatting there. I will give you a bit of leeway about testing, just append &url=testing to your call.
HOW TO PROGRAMME A CALL TO THE API
This is going to depend very much on your programming language and/or the o/s of your server.
For those with *nix servers you can just add the single line to your crontab file:
15 2 * * 1-5 WGET -q -O /var/cache/ourjobvacancies.json http://api.JobsGoLocal.org.uk/?offices=WOA|GUF
The url shown is the shorthand equivalent of:
http://api.JobsGoLocal.co.uk/index.htm?offices=WOA|GUF&format=json
json is served by default and index.htm is the default doc.
The WGET example tells the server : On Mondays to Fridays [1-5] at 02:15 go and get the output from that url and put it in a folder called /var/cache and save the file as ourjobvacancies.json
If anyone knows the Win32 equivalent AT and DOS commands to go out then please post it below.
CURL
Called similarly from a crontab entry:
15 2 * * 1-5 curl -s -o /var/cache/ourjobvacancies.json http://api.JobsGoLocal.org.uk/?offices=WOA|GUF
*TODO add an example CURL call from a script
GET STARTED
Go to the map page on the main site and pick the Jobcentre Plus Offices in your locality to assemble your API call.
If you have any questions or comments then post them below, thanks!
