Lamplight core API

Introduction

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.

Contents

  1. Conventions / styles used in this document
  2. Constructing the request
  3. Authentication credentials
  4. Other parameters used in all requests
  5. Data returned - general
  6. Requesting work records
    1. all work records
    2. some work records
    3. one work record
  7. Requesting organisation records
    1. all organisation records
    2. some organisation records
    3. one organisation record
  8. Requesting people records
  9. Requesting a list of workareas
  10. Error codes and messages

Conventions/styles in this document

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:

type/howmany

A brief description of what this does.

URI

The base uri for the request is shown:

https://lamplight.online/api/type/howmany
     

As discussed below, type will be something like work, and howmany something like some

Parameters

In the documentation below, parameters highlighted in

red
Type are required parameters
black
Type are not required. Type, in green, is String | Array | Int etc.

Returns

A list of the fields returned, plus any additional information

id
Type A description of the return value for this field.
name
Type A second field in the returned record. As above, type indicates the datatype, although it is likely that json encoding will convert all values to strings. If this is important, you may need to cast values to the proper type.

So on to the real stuff...

Constructing the request

The base uri to use is https://lamplight.online/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://lamplight.online/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://lamplight.online/api/workarea/all
// Returns some work records, depending on other query parameters passed
https://lamplight.online/api/work/some
// Returns full details about a person - an id parameter is also required
https://lamplight.online/api/people/one
   

Requests may use GET or POST to provide parameters, should use UTF-8 character encoding, and all parameters should be properly encoded.

Credentials

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:

Parameters - credentials

lampid
Int Your id - available through the admin menu of Lamplight
project
Int Project id - available through the admin menu of Lamplight. Even if you only have one project this will be needed.
key
String API key - available through the admin menu of Lamplight

All of these are required. An error response will be returned if these are omitted or incorrect

Other parameters used in all requests

There is only one other required parameter, and one optional:

Parameters - other

format
String The format of results: currently the only value available is json
callback
String Your results will be wrapped with the 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.

Data returned

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.

Requesting work records

Published work records may be requested through the API.

work/all

You may not request all work records. Use some.

work/some

URI

The uri to request some work records is

https://lamplight.online/api/work/some/
   

Parameters

num
Int Number of records (optional: default is same as 'row per page' config option in Lamplight)
start
Int Offset to start from (optional: default = 0)
order
String Field to order by. Must be a publishable field. The default is to return records sorted in ascending date order.
q
StringSearch string. All publishable fields are searched.
after
StringDate string in YYYY-MM-DD format. Will return records with date on or after that given.
before
StringDate string in YYYY-MM-DD format. Will return records with date on or before that given.
workarea
Int | StringID or comma-separated list of workarea IDs to filter by. Workareas and their IDs may be requested separately (see requesting workarea).

Returns

Each record returned will have the following fields:

id
IntThe Lamplight ID of the work records
title
StringTitle string of the record
start_date
StringThe start date, in YYYY-MM-DD hh:mm:ss format
end_date
IntThe end date, in YYYY-MM-DD hh:mm:ss format
workarea
ArrayText of workarea and any subworkareas
may_add_attend
BooleanWhether you can add attendees to this record through the API. If you do not have the datain module enabled this will always be false (added in version 1.1).

Additionally, if enabled in publishing settings, you may receive fields showing the number of users attending, and number of spaces:

num_users_attending
Int The number of users logged as attending
maximum_num_users_allowed
Int The maximum number of users allowed. Note that currently Lamplight does not enforce this: you may still add people. This is to enable you to display a 'fully booked' indicator on your listing.

Example

A worked example listing work records is available here and another showing how to search work records here.

work/one

URI

The uri to request full details of a single work record is:

https://lamplight.online/api/work/one
     

Parameters

id
Int The Lamplight ID of the record: this is the ID returned in calls to some.

Returns

Each record returned will have the following fields:

id
IntThe Lamplight ID of the work records
title
StringTitle string of the record
start_date
StringThe start date, in YYYY-MM-DD hh:mm:ss format
end_date
IntThe end date, in YYYY-MM-DD hh:mm:ss format
workarea
ArrayText of workarea and any subworkareas
workareaText
String The workarea text for the record (not sub-workareas).
subWorkareas
Array An array of strings of any sub-workareas for the record.
may_add_attend
BooleanWhether you can add attendees to this record through the API. If you do not have the datain module enabled this will always be false (added in version 1.1)

Depending on your publishing settings in Lamplight, records may also contain any of the following fields:

description
String The description entered in the work record. May include html rich-text formatting.
summary
String The summary entered in the work record. May include html rich-text formatting.
followup
String The follow up entered in the work record. May include html rich-text formatting.
location
Array Array of strings describing the location(s) of the event.
location_full_details
Array Array of objects giving more information about the locations of the record. Each object has the following structure:
name
String Name of the location
address_line_1
String Address 1
address_line_2
String Address 2
address_line_3
String Address 3
address_line_4
String Address 4
address_line_5
String Address 5
postcode
String Postcode
description
String Description of the venue
website
String Website of the venue
disabled_access
String Any text comments on accessibility of the venue
contact_phone
String Contact number for the venue

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:

Name_of_field_in_Lamplight
mixed Value, or array of values (for multi-select type fields).

Example

A worked example is available here when you click the 'more' link on one of the listed records.

Requesting organisation records

Details from published organisation profiles may be requested through the API.

orgs/all

URI

The uri to request all organisation profiles is

https://lamplight.online/api/orgs/all
     

Parameters

role
String One of user, contact, funder, org. Will return organisations with the given role.
return
String Either 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.

Returns

Each record returned will have the following fields:

id
Int The Lamplight ID of the organisation. Used in calls to one.
name
String The name of the organisation
summary
String The publishing summary for the organisation (from the 'publishing' tab in their profile).

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).

Example

A worked example listing organisations is available here.

orgs/some

URI

The uri to request some organisations is

https://lamplight.online/api/orgs/some
     

Parameters

role
String One of user, contact, funder, org. Will return organisations with the given role.
num
Int Number of records (optional: default is same as 'row per page' config option in Lamplight)
start
Int Offset to start from (optional: default = 0)
order
String Field to order by. Must be a publishable field. The default is to return records sorted in ascending name order.
q
StringSearch string. All publishable fields are searched.
return
String Either 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.
near
String A geographic identifier to search for organisations near to. This can be a UK postcode, a latitude/longitude, or a northing/easting. Lamplight will first check if it's a valid UK postcode, and if that fails, use the presence of a decimal place to decide if it thinks it's Lat/Lng or Northing/Easting. Moral is, don't send Northing/Easting requests with decimal points in. So, for example, any of 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.
nearRadius
Int The radius of the circle to look in around the 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://lamplight.online/api/people/some/First_language/English
      

Returns

Each record returned will have the following fields:

id
Int The Lamplight ID of the organisation. Used in calls to one.
name
String The name of the organisation
summary
String The publishing summary for the organisation (from the 'publishing' tab in their profile).

Example

A worked example searching organisations available here.

orgs/one

URI

The uri to request details for a single organisation is

https://lamplight.online/api/orgs/one
     

Parameters

id
Type

Returns

Each record returned will have the following fields:

id
Int The Lamplight ID of the record
name
String The organisation name.

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).

address_line_1
String Line 1 of the address
address_line_2
String Line 2 of the address
address_line_3
String Line 3 of the address
address_line_4
String Line 4 of the address
address_line_5
String Line 5 of the address
postcode
String Postcode
email
String Email address
web
String The organisation's website address
phone
String Their phone number
mobile
String Their mobile phone number

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"}
  ]
  
     

Example

A worked example organisations is available when you view the listing of organisations here and click the 'more' link from one of those published.

Requesting people records

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:

Requesting a list of workareas

workarea/all

URI

The uri to request all workareas is

https://lamplight.online/api/workarea/all
     

Parameters

There are no parameters.

Returns

Each record returned will have the following fields:

id
Int The Lamplight ID of the workarea. May be used in filtering some work records.
text
String The workarea text.
children
Array An array of 0 or more sub-workareas for the parent. Each object in the array will have id and text fields.

Example

A listing of workareas is included in the search work records example here.

workarea/some

You may not request some workareas.

workarea/one

You may not request one workarea.

Error messages

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.

1001
"Role of person not recognised" The role parameter was invalid. May be returned to person or organisation requests.
1002
"Person of type requested is not publishable" Either the global publishing settings do not allow publishing of this type of person/organisation, or the particular one being requested is not published.
1003
"Only people or organisations may be requested" Internal error.
1004
"Method not recognised: should be one of all, some or one" What it says: your uri is incorrect.
1005
"Method all not permitted with work records"
1006
"Work records are not publishable" Either the global publishing settings do not allow publishing of work records, or the particular one being requested is not published.
1007
"An unknown error occurred. It is likely an unpublished record was requested". The most likely situation that this error will be returned is if a non-existent, or non-published record is requested (perhaps by manually changing an ID value).

php client

If you are using the php client, it will add a couple of error codes (starting 11xx):

1100
The response could not be parsed as json, but the response status was 200 OK.
1101
A strange error: the server did not return a 200 OK, the response was parsed as json, but did not include an error code and message from the server. Basically, you shouldn't ever see this error.

The php client documentation has more information on retrieving error codes/responses.