The core API is what you use to request data from the Lamplight servers. Lamplight offers a fairly simple Query interface to request data, which is returned in json format (although we may add alternatives in due course).
You will need an API key and access parameters from Lamplight to access data: these are available to system administrators through the admin menu within Lamplight.
Additional API information for the 'datain' module (that lets you add data to Lamplight via the API) can be found in it's own section.
After the introductory sections, the details of how to construct the query are split into sections by type of record: work, organisation, people and workarea. Each section is of the following form:
A brief description of what this does.
The base uri for the request is shown:
https://www.lamplight3.info/api/type/howmany
As discussed below, type will be something like work, and howmany something like some
In the documentation below, parameters highlighted in
A list of the fields returned, plus any additional information
So on to the real stuff...
The base uri to use is https://www.lamplight3.info/api
.
To this uri, you need
to append two parameters, separated by a forward slash (/), which describe
what kind of data you want, and the type of request:
https://www.lamplight3.info/api/what/howmany
.
Here, what must be one of:
and howmany must be one of:
There are some restrictions on how you may combine these (for example,
you can only request workarea/all
).
For example:
// Returns a list of all workareas https://www.lamplight3.info/api/workarea/all // Returns some work records, depending on other query parameters passed https://www.lamplight3.info/api/work/some // Returns full details about a person - an id parameter is also required https://www.lamplight3.info/api/person/one
Requests may use GET or POST to provide parameters, should use UTF-8 character encoding, and all parameters should be properly encoded.
There are three access credentials that are required: your Lamplight ID, a project ID, and your customer API key. These must be provided with the request, either as GET or POST parameters. If you append them as a query string, they must appear after the what and howmany parameters described above.
The parameter names are:
All of these are required. An error response will be returned if these are omitted or incorrect
There is only one other required parameter, and one optional:
json
callback({/*data*/})
you specify. This may be used
in javascript implementations to enable you to process the data once it
is added to the page.
Note that using javascript means that you will inevitably make your access credentials public; in many cases this will not be desirable. We recommend that you set up a simple server proxy if you wish to use javascript, that can append access credentials at the server, and pass returned data straight through.
In some cases you can use custom fields as parameters (for example, to search by 'services offered'. In these cases, field names should use the underscore character instead of spaces, and be lower case.
Currently the only format available is json. Data will be returned as an
object with two keys: data
and meta
. Data holds
the actual record(s), meta holds a small amount of meta information. For
example:
{ data: [ {id:1, title:"This is a test record"}, {id:2, title:"This is another"} ],meta:{ numRecords: 2, totalRecords: 20 } }
(White space added for readability). The fields in the data array will vary.
Published work records may be requested through the API.
You may not request all
work records. Use some
.
The uri to request some work records is
https://www.lamplight3.info/api/work/some/
Each record returned will have the following fields:
Additionally, if enabled in publishing settings, you may receive fields showing the number of users attending, and number of spaces:
A worked example listing work records is available here and another showing how to search work records here.
The uri to request full details of a single work record is:
https://www.lamplight3.info/api/work/one
some
.
Each record returned will have the following fields:
Depending on your publishing settings in Lamplight, records may also contain any of the following fields:
If you have published custom fields on work records, these will also be listed. In the same way as for profile data, you will see the field name with spaces replaced by underscores:
A worked example is available here when you click the 'more' link on one of the listed records.
Details from published organisation profiles may be requested through the API.
The uri to request all organisation profiles is
https://www.lamplight3.info/api/orgs/all
user
, contact
, funder
,
org
. Will return organisations with the given role.
short
or full
. If nothing is
passed, will return the short response shown below in the
Returns section. If full
is used, the return value
will be an array of objects, each with data as shown in
org/one returns section.Each record returned will have the following fields:
one
.
For performance reasons, even when requesting all records Lamplight
will return the first 25 (ordered by name) records. You can
change this using parameters num
and start
.
The meta
data returned will list the number of records in the current
response (numRecords
), and the total number of records
(totalRecords
).
A worked example listing organisations is available here.
The uri to request some organisations is
https://www.lamplight3.info/api/orgs/some
user
, contact
, funder
,
org
. Will return organisations with the given role.
short
or full
. If nothing is
passed, will return the short response shown below in the
Returns section. If full
is used, the return value
will be an array of objects, each with data as shown in
org/one returns section.W2 1FT
or 51.1082257095090000,-1.0293690518454999
or
134773,468047
will work. Geographic search was added in version 2.1.
Note that address information will need to have been previously geo-coded in Lamplight
for results to be returned.
near
location, in metres.In addition, you may also append multiple fieldname/value pairs to the request. If these fields are recognised as publishable fields data will be filtered using a 'contains' match.
This means that we strongly recommend that your custom fields do not contain underscores (_), as there will be no way to distinguish between spaces and underscores, and the field will not be recognised.
For example:
https://www.lamplight3.info/api/people/some/First_language/English
Each record returned will have the following fields:
one
.
A worked example searching organisations available here.
The uri to request details for a single organisation is
https://www.lamplight3.info/api/orgs/one
Each record returned will have the following fields:
Records may contain the following fields, depending on publishing settings. If a field is published it will be returned, even if it is empty (updated 23/07/2012 - prior to this empty fields were omitted).
Records may additionally contain publishable custom fields. Field names will be the field names with spaces replaced by underscores (_). Return values will depend on the field type.
Multi-select fields will return arrays of strings.
All other 'non-repeating' fields will return strings. Non-repeating fields are those that are not linked to others in Lamplight, and so can only have a single value.
Repeating (linked) fields will be returned as an array. The field name for the array will be the first field in the set. Each object in the array will contain the fields and associated values, for example:
Repeating_field_1: [ {Repeating_field_1: "value 1", Repeating_field_2: "val 2"}, {Repeating_field_1: "value 3", Repeating_field_2: "val 4"} ]
A worked example organisations is available when you view the listing of organisations here and click the 'more' link from one of those published.
Details from published profiles of people may be requested through the API.
The API details are identical to those for requesting organisations, with the following exceptions:
https://www.lamplight3.info/api/person/all https://www.lamplight3.info/api/person/some https://www.lamplight3.info/api/person/one
org
is not valid for people. The role staff
may be used.
one
person will return fields first_name
and surname
.
The uri to request all workareas is
https://www.lamplight3.info/api/workarea/all
There are no parameters.
Each record returned will have the following fields:
some
work records.
id
and text
fields.
A listing of workareas is included in the search work records example here.
You may not request some
workareas.
You may not request one
workarea.
If there is an error in your request, the server will return an HTTP 400 code, and the body of the response will contain a json encoded error object. Error codes returned by Lamplight start 10xx.
role
parameter was
invalid. May be returned to person or organisation requests.
If you are using the php client, it will add a couple of error codes (starting 11xx):
The php client documentation has more information on retrieving error codes/responses.