Welcome to the BLUF calendar API

This is a simple test page for the BLUF calendar API, which returns JSON formatted data for the public entries in the BLUF calendar. It will be expanded with fuller documentation over time. Essentially, the API allows you to retrieve all the public events listed in the BLUF calendar, together with links to the images we have for them, and in some cases also the map coordinates of the event. You can request all the events, or just a single one, or select by city, country or classification (BLUF events, title contests, cultural events).

You can call to the BLUF calendar using jQuery, posting to the calendar API endpoint, which is https://bluf.com/api/calendar.php or (preferably) https://api1997.net/calendar.php.

Calls have one or two parameters; the ACTION parameter is mandatory, and specifies what data you are requesting. The OPTION parameter is used on some calls to specify parameters. All commands return information in a similar format; the top level contains a status, which may be ok, or error; an error will also contain a 'code' which is a numeric and an 'info' description. A 'server' array gives the current API version, and the timestamp on the BLUF server (which is always in UTC). For example, POSTing without using a secure connection will return the results

{
  "status": "error",
  "info": "Insecure connection",
  "code": 105,
  "server": {
    "timestamp": 1385569686,
    "api": 1
  }
}

For a successful call, the 'info' will be set to the type of data retrieved, and an array of the same name will be returned. For example, for most queries, the info will be "calendar" and there will be a "calendar" array, containing an entry for each event found. You can explore the data using the form below. The command can be in upper, lower or mixed case, but the parameter names ACTION and OPTION are case sensitive. Note that in the results, some entries may be 'null' for certain items; they should all be present however.

Using the calendar

Please feel free to use this calendar on your own site. But credit the source, eg Event calendar from BLUF.com, or use the image at the top of this page. To link directly to an event on the calendar, please use https://bluf.com/e/{eventid} for example https://bluf.com/e/676. For a sample calendar plug-in, click here.

Basic example

This minimal jQuery example will fetch all future BLUF events from the calendar:

$.post("https://api1997.net/calendar.php", { ACTION: "getclass", OPTION: "bluf" } )
 .done(function(data) {
	// do something with the JSON data
}) ;

This is the current list of API calls. (v4, March 2019)

LASTUPDATE returns the UNIX timestamp of the last change to the calendar data

LASTDELETE returns the UNIX timestamp of the last deletion of a calendar item

GETALL returns all the future public events in the calendar

GETCHANGES returns all entries changed since the timestamp specified with OPTION

GETDELETED returns a list of events deleted since the timestamp specified with OPTION

COUNTRIES returns a list of all the countries in which events are taking place

CITIES returns a list of all the cities in which events are taking place

GETCITY returns all events in the city specified with OPTION

GETCOUNTRY returns all events in the country specified with OPTION; use either the country names shown by COUNTRIES, or ISO 2 letter codes (gb, us, pl etc)

GETCLASS returns all events of the class specified with OPTION (bluf,contest,cultural)

GET returns the event specified with OPTION (a numeric id)

Explore the calendar info

To see what data is available in the calendar, select a command and enter an option, then click Fetch. For help or assistance, please contact the BLUF webmaster.

Note that from v4, events that are marked as cancelled will have "CANCELLED:" prepended to their title

Also from v4, a new png1024 parameter in the event data contains a URL that returns the event poster in PNG format, scaled to no more than 1024 pixels along its longest side.

OPTION =