The JSON Application Programming Interface to the Jobcentre Plus Mirror

Another kind of Workbench

This is the front-page to the JSON API on the Jobcentre Plus Mirror database. It allows easy access for programs wishing to interrogate this system and add value to it.

Calling Conventions

All the functions exist as PHP programs available on home.zois.co.uk, using the HTTP protocol on the 'alternative' HTTP well-known port, 591. The PHP programs take a single input (json_in) encoded in JSON as a HTTP POST and return a single output (json_out), again encoded in JSON. For consistency the functions are all named json_<something> and the calling convention is always used, even when the simplicity of the input or output would suggest otherwise. Sample clients are provided, written in Perl (but some are available in other language on request from the author.

The narrative refers to a 'reference' datum. This is the unique reference provided by the underlying Labour Market System (LMS), the database of which is the ultimate repository of the desired data. The ZOIS JCPM system continue to use this reference in the belief that it provides a unique indicator. The 'reference' can also be used to access the original data (see TN-2010-02-17 for an example of how this is done).

Functions Available

json_get_details_by_reference

Json_get_details_by_reference returns the details of a vacancy identified by an LMS reference, which take the form a string with a three-letter prefix identifying an office and a numerical suffix, divided by a slash ('/'). The function is designed to allow the maximal retrieval of all of an offices details for a previously identified given reference.

A sample client is available written in Perl.

Input:

reference: A string LMS reference.

Outputs:

title: A string with the Title of the vacancy.
location: A string with the Location of the vacancy.
hours: A string with the Working Hours of the vacancy.
wage: A string with salary details of the vacancy.
work_pattern: A string with shift-pattern details of the vacancy.
employer: The string with the Employer Name in it.
employer_ref: As string sometimes a reference internal to the Employer sometimes a reference to the employer.
pension: A string indication if a pension is available with this vacancy.
duration: A string demoting the duration of the employment Contract (currently represented as a single character. 'P' indicates a permanent contract, 'T' a temporary one).
closing_date: A string containing an ISO-8601 representation of the date the vacancy is noted to close as posted on the Jobseekers Direct web-site.
description: A string with the vacancy description.
apply: A string with Application details.
added: A string continuing an ISO-8601 representation of the date the vacancy was officially posted to the Jobseekers Direct web-site.
noted: A string containing an ISO-8601 representation of the date and time the vacancy was retrieved by the JCPM system from the Jobseekers Direct web-site.

json_find

Json_find gives program access to the find interface as documented in TN-2010-11-11: The Jobcentre Plus Mirror Find Interface. The interface allows the submission of an arbitrary string which is decoded according to rules presented in the above TN and a result returned containing summary details for the vacancies found. The result can also be 'null' or an arbitrary string documenting a failure. Unlike its web-site based cousin, this interface does not make suggestions should a query fail (you'll just get a 'null').

A sample client is available written in Perl.

Input:

pattern: A string used to query the JCPM database. It takes the form of two distinct search clauses, the first of which is series of white-space separated tokens that are matched to entries in the details field of the database. The string can be quoted (for example 'pastry chief'), so that blanks become significant. The tokens can be connected using logical operators, for example 'or', 'and' and 'not', or their more symbolic versions ('|', '&' and '!'). Adjacent tokens are silently 'and-ed' together. So, 'pastry chief', without the quotes, becomes 'pastry AND chief'; the two terms are matched anywhere with in the description. A second clause introduced by the key-word 'in' does a similar job on location. As before tokens can be contain blanks, and be logically connected, but in this instance the search results are limited to Jobcentre Offices where the location has appeared in any previously seen vacancies' location field. Thus if the location 'wakefield' has appeared in any Job Vacancy found in say Barnsley (Cooper House, code BAL) then that office will be searched for the vacancy too. It is hoped that a degree of localisation can thus be afforded were no specific information exists.
Should the query fail, null will be returned. Should the tokeniser or the underlying search mechanism report an error these will be returned as strings. Although they may be parsed, experience has found that the easiest course of action is to report a generalised error and invite the user to try again.

Outputs:

The output can be null or an error string, so these values should be tested for. Otherwise an annotated array of the following items is returned.

title: A string with the Title of the vacancy.
reference: A string LMS reference.
location: A string with the Location of the vacancy.
added: A string containing an ISO-8601 representation of the date the vacancy was officially posted to the Jobseekers Direct web-site.
office: The name of the Jobcentre Office holding the vacancy.
office_code: A string containing the three letter code for the Jobcentre Office holding the vacancy.
office_count: A count defining the number of times a location has been matched for a particular Jobcentre Office. This may be used as a measure of the 'closeness' of location. The value of zero is returned if there is no 'in' clause in the search pattern.

json_find_all

Json_find_all is similar to json_find in that gives program access to the find interface as documented in TN-2010-11-11: The Jobcentre Plus Mirror Find Interface. The interface allows the submission of an arbitrary string which is decoded according to rules presented in the above TN but rather than return a summary it returns a comprehensive set of details for the vacancies found. The result can also be 'null' or an arbitrary string documenting a failure. Unlike its web-site based cousin, this interface does not make suggestions should a query fail (you'll just get a 'null').

A sample client is available written in Perl.

Input:

pattern: A string used to query the JCPM database. It takes the form of two distinct search clauses, the first of which is series of white-space separated tokens that are matched to entries in the details field of the database. The string can be quoted (for example 'pastry chief'), so that blanks become significant. The tokens can be connected using logical operators, for example 'or', 'and' and 'not', or their more symbolic versions ('|', '&' and '!'). Adjacent tokens are silently 'and-ed' together. So, 'pastry chief', without the quotes, becomes 'pastry AND chief'; the two terms are matched anywhere with in the description. A second clause introduced by the key-word 'in' does a similar job on location. As before tokens can be contain blanks, and be logically connected, but in this instance the search results are limited to Jobcentre Offices where the location has appeared in any previously seen vacancies' location field. Thus if the location 'wakefield' has appeared in any Job Vacancy found in say Barnsley (Cooper House, code BAL) then that office will be searched for the vacancy too. It is hoped that a degree of localisation can thus be afforded were no specific information exists.
Should the query fail, null will be returned. Should the tokeniser or the underlying search mechanism report an error these will be returned as strings. Although they may be parsed, experience has found that the easiest course of action is to report a generalised error and invite the user to try again.

Outputs:

The output can be null or an error string, so these values should be tested for. Otherwise an annotated array of the following items is returned.

title: A string with the Title of the vacancy.
reference: A string LMS reference.
location: A string with the Location of the vacancy.
hours: A string with the Working Hours of the vacancy.
wage: A string with salary details of the vacancy.
work_pattern: A string with shift-pattern details of the vacancy.
employer: The string with the Employer Name in it.
employer_ref: As string sometimes a reference internal to the Employer sometimes a reference to the employer.
pension: A string indication if a pension is available with this vacancy.
duration: A string demoting the duration of the employment Contract (currently represented as a single character. 'P' indicates a permanent contract, 'T' a temporary one).
closing_date: A string containing an ISO-8601 representation of the date the vacancy is noted to close as posted on the Jobseekers Direct web-site.
description: A string with the vacancy description.
apply: A string with Application details.
added: A string continuing an ISO-8601 representation of the date the vacancy was officially posted to the Jobseekers Direct web-site.
noted: A string containing an ISO-8601 representation of the date and time the vacancy was retrieved by the JCPM system from the Jobseekers Direct web-site.
office: The name of the Jobcentre Office holding the vacancy.
office_code: A string containing the three letter code for the Jobcentre Office holding the vacancy.
office_count: A count defining the number of times a location has been matched for a particular Jobcentre Office. This may be used as a measure of the 'closeness' of location. The value of zero is returned if there is no 'in' clause in the search pattern.

json_get_summary_since

Get_summary_since is designed to be called on a reasonably frequent bases, but please, not excessively so. It provides a sequence of vacancy summaries that have been posted since some noted time. The summaries are designed to be used in some-kind of scrolling tableaux, the design of which is left to the user.

Should greater detail be required then the programmers attention is drawn to json_get_details_by_reference, seen above.

A sample client is available written in Perl.

Input:

time_stamp: A string containing an ISO-8601 representation of the date and time the last time the service was run. Can be null, in which case the default time is the 'epoch' and the last 1000 vacancies will be retrieved.

Output:

The output consists of an array of two items.

time_stamp (element 0): A string containing an ISO-8601 representation of the date and time the last time the service was run. This may be used as an input to future runs of the services.

The second item of the array (element 1) is an array itself, with the following items:

title: A string with the Title of the vacancy.
reference: A string LMS reference.
location: A string with the Location of the vacancy.
added: A string containing an ISO-8601 representation of the date the vacancy was officially posted to the Jobseekers Direct web-site.
office: The name of the Jobcentre Office holding the vacancy.
office_code: A string containing the three letter code for the Jobcentre Office holding the vacancy.
office_count: A count defining the number of times a location has been matched for a particular Jobcentre Office. This may be used as a measure of the 'closeness' of location. The value of zero is returned if there is no 'in' clause in the search pattern.

Thank you for your interest.

~Z~