Lamplight API - core API documentation

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://www.lamplight3.info/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://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:

work
workarea
person
orgs

and howmany must be one of:

one
some
all

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.

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://www.lamplight3.info/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://www.lamplight3.info/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://www.lamplight3.info/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://www.lamplight3.info/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://www.lamplight3.info/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://www.lamplight3.info/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:

'org' should be replaced by 'person' in the request URI:

https://www.lamplight3.info/api/person/all
https://www.lamplight3.info/api/person/some
https://www.lamplight3.info/api/person/one

The role org is not valid for people. The role staff may be used.
A request for one person will return fields first_name and surname.

Requesting a list of workareas

workarea/all

URI

The uri to request all workareas is

https://www.lamplight3.info/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.

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.

Lamplight core API

Introduction

type/howmany

URI

Parameters

Returns

Parameters - credentials

Parameters - other

URI

Parameters

Returns

Example

URI

Parameters

Returns

Example

URI

Parameters

Returns

Example

URI

Parameters

Returns

Example

URI

Parameters

Returns

Example

URI

Parameters

Returns

Example

php client