Publish content through the API

The Api can be used to create, edit and delete events, locations and agendas.

An authentication process needs to be followed, which follows the 2-legged form of the OAuth 2.0 standard: Using a secret key (which you never ever share with anyone), you start by getting an access token which you then attach to your requests to authenticate them.

Generating your own secret key from your OpenAgenda account is a feature that is activated by sending a request at the following email: [e-mail]

Once you have a valid access token, you can either handle locations, events or agendas . Keep the following in mind:

• Before publishing events, you will need to create the locations at which they will take place and use their uids as reference.
• If you need to test the api, remember not to publish the events you are creating as they will be directly visible to the public on the platform.
• There is a limitation of 100 event creations per day set mainly for security purposes. Contact us if you think you will need to publish more.
• If you need to exploit the api a bit heavily (like publishing hundreds of events), we'd appreciate it if you ran your scripts during low traffic periods (night time).

To get you started, we suggest you

• Start by reading the Authentication section to see how you can get a valid access token
• Move on to the Locations section to create a bunch of locations which you will then use to create your events (keep track of their uids!)
• Create your first event following the data structure detailed in the Events section
• And optionnally, register your newly created event to one of your agendas by following the agendas section

Publishing on OpenAgenda - Authentication

Synch your event data on a OpenAgenda agenda

Principle

To publish content on OpenAgenda, you need to authenticate yourself by following the procedure described here. It follows (roughly) OAuth 2.0's 2-legged approach.

• You send a request with your secret attached to the authentication server to give you an access token..
• The server sends you back an access token which you can then use to access protected resources.
• That's pretty much it. The access token has a limited lifespan, specified in the response. So when it goes back, go through this small procedure again.

Specifically..

https://api.openagenda.com/v1/requestAccessToken

Send a request at the above resource with your secret as a post parameter named 'code'. If successful, you'll get a json-encoded response containing two parameters.

• access_token: The access token which will allow you to access protected resources (Yeepee!)
• expires_in: Your access token's life expectancy in seconds.

How is this secure?

You are using https. Regenerate your secret now and then, you know, just in case.

Example - php

Here is a quick example with curl in php:

$ch = curl_init('https://api.openagenda.com/v1/requestAccessToken');

curl_setopt($ch, CURLOPT_POST, true);

curl_setopt($ch, CURLOPT_POSTFIELDS, array(
  'grant_type' => 'authorization_code', 
  'code' => '--yoursecretgoeshere--'
));

$received_content = curl_exec($ch);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200)
{
  $data = json_decode($received_content, true);

  $accessToken = $data['access_token'];
}

Example - node.js

Another example, this time using node.js

var https = require('https');
var querystring = require('querystring');


var post_data = querystring.stringify({
  'grant-type' : 'authorization_code',
  'code': '--yoursecretgoeshere--',
});

var options = {
  host: 'api.openagenda.com',
  path: '/v1/requestAccessToken',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': post_data.length
  }
};

var request = https.request(options, function (response) {

  var str = '';

  response.on('data', function (chunk) { str += chunk; });

  response.on('end', function () {

    if (response.statusCode == 200) {

      var access_token = JSON.parse(str).access_token;

      console.log(access_token);

    }

  });
});

request.write(post_data);
request.end();

Publishing on OpenAgenda - Locations

Your events need to be associated to locations at creation. So unless you've already got some location references (uids) with you ready to be used, you need to create some locations before starting to create events.

Creating a location

To create a location, use https://api.openagenda.com/v1/locations.

Both PUT and POST methods are accepted. The parameters you need to include in the body of your request are:

• access_token: your valid access token.
• nonce: a unique random number to be used this once only. Regenerate a new one at each request.
• data: the json encoded data required to create the location. The names of the required fields are self explanatory and are: placename, address, latitude, longitude.

Example - php

$ch = curl_init("https://api.openagenda.com/v1/locations");

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');

curl_setopt($ch, CURLOPT_POSTFIELDS, array(
  'access_token' => '--avalidaccesstoken--',
  'nonce' => randomnumber,
  'data' => json_encode(array(
    'placename' => 'Fucking',            // a real place
    'address' => 'Fucking, Austria',
    'latitude' => 48.067512,
    'longitude' => 12.862532
  ))
));

$received_content = curl_exec($ch);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200)
{
  $data = json_decode($received_content, true);

  $location_uid = $data['uid'];
}

Example - node.js

var https = require('https');
var querystring = require('querystring');

var access_token = '--youraccesstoken--';
var nonce = '--auniquenumber--';

var location_data = querystring.stringify({
  'access_token' : access_token,
  'nonce': nonce,
  'data': JSON.stringify({
    placename: 'Titty Ho',
    address: 'Raunds, Wellingborough, Northamptonshire',
    latitude: 52.339954,
    longitude: -0.545178
  })
});


var request = https.request({
  host: 'api.openagenda.com',
  path: '/v1/locations',
  method: 'PUT', // or POST
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': location_data.length
  }
}, function (response) {

  var str = '';

  response.on('data', function (chunk) { str += chunk; });

  response.on('end', function () {

    if (response.statusCode == 200) {

      // remember the uid of your location, 
      // you'll need it for publishing events occurring there
      var location_uid = JSON.parse(str).uid;

    }

  });
});

request.write(location_data);
request.end();

Publishing on OpenAgenda - Events

Publish the events according to locations

There are a bunch of resources at your disposal to allow you to handle your events on OpenAgenda. In all cases, you need to set valid access_token and nonce parameters in the body of your request. When additional data is required (creating or editing), it goes in a json encoded array set in a data parameter.

• Check the event data structure you'll need to follow when making requests
• /v1/events method: put or post

  Create a new event

• /v1/events/[uid] method: post

  Edit an event

• /v1/events/[uid] method: delete

  Delete an event

• /v1/events/[uid]/locations/[location_uid] method: delete

  Remove association of event with location.

• /v1/events/[uid]/locations/[location_uid]/dates/[date] method: delete

  Remove occurrences of event at location at date

Event data structure

Overview

Here is an list of the fields defining an event:

• title: Title of the event. Required. Multilingual. This field cannot exceed 140 characters.
• description: Short description of the event. Multilingual. This field cannot exceed 200 characters.
• freeText: Long description of the event. Multilingual. This field can contain up to 6000 characters. Links posted here to youtube videos, soundcloud music, flickr images or direct image links will be rendered on the event page.
• tags: Comma separated tags describing the event. Multilingual. This field cannot exceed 255 characters.
• locations: List of locations associated with events. Also contains dates and timing information at each location reference. More info in subsection below.

Multilingual fields

Title, description, free text and tags fields can be given in several languages.

If you only need to publish your event in one language, specify its code in the lang and fill in your descriptive fields directly with your text content.

{
  'title': 'Baixo Calão, Warpath et Devour the Fetus',
  'description': 'Une soirée grindcore et thrash ne peut promettre qu'une chose : les caisses claires seront mise à rude épreuve',
  'freeText': 'https://www.facebook.com/events/301760259894322/   BAIXO CALÃO: https://www.facebook.com/pages/Baixo-Cal%C3%A3o/243906019001026?sk=app_2405167945    brazil grindcore   WARPATH   brazil thrash metal // www.myspace.com/warpathband',
  'tags': 'grindcore, thrash, concert'
}

sample javascript array of an event in french only

If on the other hand you want to publish your event in several languages, do not use the lang field and in each descriptive field, set a list of all language specific texts indexed by their language codes. Be aware that once you decide to use several languages, required fields become required in each language you intend to use.

{
  'title': {
    'en': 'La Grande Prairie', 
    'fr': 'La Grande Prairie'
  },
  'description': { 
    'en': 'The ideal place to hang out and listen to acoustic concerts and djs sets',
    'fr': 'L’écrin idéal pour des concerts acoustiques et djs sets'
  },
  'freeText': {
    'en': 'Discover this old hall fitted and arranged to ressemble a prairie with hamacs and ....',
    'fr': 'Imaginez cette ancienne salle Jean Jaurès, métamorphosée en vaste surface herbeuse, ....'
  },
  'tags': {
    'en': 'grande prairie, bellevilloise, summer, concerts',
    'fr': 'grande prairie, bellevilloise, été, concerts'
  }
}

sample javascript array of an event in french and english

Available languages are listed here. If you need to use onother one, contact us and we'll add it.

• english (en)
• french (fr)
• spanish (es)
• german (de)
• italian (it)
• dutch (ne)
• portugese (pt)
• arabic (ar)
• icelandic (is)

Locations list

OpenAgenda events can occur in multiple locations and at different times. As timings are location specific, they are listed in each item of the locations list of the event. Here are the fields included in an item of the location list:

• uid: Required. uid of the location to associate with the event
• ticketLink: Optional. A link to the ticketing service for the event at the location. Has to start with http:// or https://
• pricingInfo: Optional and Multilingual. Some information on the pricing. Should not be more than 255 characters.
• dates: Required. List of the timings to associate with the location for the event

Each item of the list of dates follows this structure:

• date: Required. Date of the timing. Should follow the structure 'Y-m-d' (example: '2012-08-22').
• timeStart: Required. Starting time. Should follow the structure 'h:i' (example: '17:00').
• timeEnd: Required. End time. Should follow the structure 'h:i' (example: '17:00').

Example of a complete event definition

Here is the data structure for an event in a single language, with one date and one location.

$eventData = array(
  'title' => 'Tango Connection - Festival d\'Ile de France',
  'description' => 'Tango au Bataclan',
  'freeText' => 'Cet événement fait partie du Festival d'Ile De France',
  'tags' => 'tango, festival ile de france, le bataclan',
  'locations' => array(
    array('uid' => --uidofbataclan--, 'dates' => array(
      array('date' => '2012-10-14', 'timeStart' => '17:00', 'timeEnd' => '22:30'),
    )),
  )
);

Creating a new event

General info

The limit of events a user can publish per day through the api is set to 100. Contact us if that is insufficient for you.

If you plan on using the api via a scheduled script running regularly, be nice and make it run at late hours or at night.

Request content

Send your request at /v1/events

Method should be put or post

Required parameters to be set in the body of the request: access_token, nonce and data. data contains the description of the event as detailed in the Event Data Structure section.

Optional parameters are:

• test: set it to true to prevent the creation of an event after the data has been processed.
• publish: set to false to create event without publishing it. An unpublished event is only visible to its creator through an open session on the site and can be published at any time.
• lang: used for single language events. Set it to the language code corresponding to the language used for the description of your event.
• image: used when you want to upload an image.

Examples

Using php curl

$ch = curl_init('https://api.openagenda.com/v1/events');

curl_setopt($ch, CURLOPT_POST, true);

$eventData = array(
  'title' => array(
    'fr' => 'Exposition du Collectif 59Rivoli',
    'en' => 'Exhibition at the 59Rivoli building'
  ),
  'description' => array(
    'fr' => 'Venez nombreux voir l'exposition d'une semaine des artistes de l'été du 59Rivoli !',
    'en' => 'Come in great numbers see this weeks exhibition from the summer artists of the 59Rivoli !',
  ),
  'tags' => array(
    'fr' => 'paris, exposition, gratuit, collective, art visuel, collage, peinture, photographie',
    'en' => 'paris, exhibition, free, building, collective, visual arts, painting, photography'
  ),
  'locations' => array(
    array('uid' => --uidof59rivoli, 'dates' => array(
      array('date' => '2012-08-31', 'timeStart' => '13:00', 'timeEnd' => '20:00'),
      array('date' => '2012-09-01', 'timeStart' => '13:00', 'timeEnd' => '20:00'),
      array('date' => '2012-09-02', 'timeStart' => '13:00', 'timeEnd' => '20:00'),
    ))
  )
);

// path of your pic.
$imagePath = '@' . dirname(__FILE__) . '/picoftheevent.jpg';

curl_setopt($ch, CURLOPT_POSTFIELDS, array(
  'access_token' => '--youraccesstoken--',
  'nonce' => '--uniquenumbertouseonce--',
  'image' => $imagePath,
  'publish' => false, // do not publish this event at creation
  'data' => json_encode($eventData)
));

$received_content = curl_exec($ch);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200)
{
  $data = json_decode($received_content, true);

  $event_uid = $data['uid'];
}

Using node

function create_event(access_token, nonce, callback)
{
  var event_data = {
    'title': 'ZomBIFFF Night #2',
    'description': 'Umberto + Necro Deathmort + Joy As A Toy + Aniaetleprogrammeur + DesiCobra',
    'tags': 'concert, brussels, festival, electronic, doom, zombie, rock, cybergrind, massacre',
    'freeText': 'Cheap Satanism Records is again partner of the Brussels International Fantasy Film Festival and welcomes you to second edition of the ZomBIFFF Night. Last year, the first edition brought you Zombie Zombie, Cercueil, Philippe Petit and all the Cheap Satanism Records bands. They have all delivered an eye-popping bunch of gigs. The second edition will host 5 live acts followed by an after-party powered by Radio Campus.',
    'locations': [
      {'uid': 10449248, 'dates': [
        {'date': '2013-04-07', 'timeStart': '19:30', 'timeEnd': '05:00'},
        {'date': '2013-04-08', 'timeStart': '20:00', 'timeEnd': '05:00'}
      ]}
    ]
  };

  var request_body = querystring.stringify({
    'access_token': access_token,
    'nonce': nonce,
    'lang': 'en',
    'publish': false,
    'data': JSON.stringify(event_data)
  });


  var request = https.request({
    host: 'api.openagenda.com',
    path: '/v1/events',
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Content-Length': request_body.length
    }
  }, function (response) {

    var str = '';

    response.on('data', function (chunk) { str += chunk; });

    response.on('end', function () {

      if (response.statusCode == 200) {

        var event_uid = JSON.parse(str).uid;

        callback(event_uid);

      } else {

        callback(false);

      }

    });
  });

  request.write(request_body);
  request.end();

}

Editing an event

General Info

You can submit any part of an event specifying its uid following the the data structure described in the section above.

Request Content

Send your post requests at /v1/events/--uidoftheeventtoedit--.

Required parameters are access_token, nonce and data

You may need to use lang as well if you are handling a single language.

Other optional fields are:

• image: used when you want to upload an image.
• publish: use to publish or unpublish an event. Set false to unpublish, anything else to publish.

Examples

In php: changing title and tags and add a location with a bunch of dates

$ch = curl_init("https://api.openagenda.com/v1/events/$eventUid");

$eventData = array(
  'title' => 'Modified title',
  'tags' => 'modified, tags, are, listed, here'
  'locations' => array(
    // add a location to your event. If location is already associated to event, dates are looked at and added if new
    array('uid' => 45253252, 'dates' => array(
      array('date' => '2012/09/05', 'timeStart' => '10:00', 'timeEnd' => '18:00'),
      array('date' => '2012/09/10', 'timeStart' => '20:00', 'timeEnd' => '22:00')
    ))
  )
);

curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, array(
  'access_token' => '--youraccesstokenhere--',
  'nonce' => '--auniquenumbernottoberepeated--',
  'lang' => 'en',
  'data' => json_encode($eventData)
));

$received_content = curl_exec($ch); 

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) == 200)
{
  $data = json_decode($received_content, true);

  $event_uid = $data['uid'];
}

In node: changing the title and publishing the event

function edit_event(uid, access_token, callback)
{
  var event_data = {'title': 'I am your father.'};

  var request_body = querystring.stringify({
    'access_token': access_token,
    'nonce': --uniquenubmer--,
    'lang': 'en',
    'publish': 'on',
    'data': JSON.stringify(event_data)
  });


  var request = https.request({
    host: 'api.openagenda.com',
    path: '/v1/events/' + uid,
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Content-Length': request_body.length
    }
  }, function (response) {

    var str = '';

    response.on('data', function (chunk) { str += chunk; });

    response.on('end', function () {

      if (response.statusCode == 200) {

        var event_uid = JSON.parse(str).uid;

        callback(event_uid);

      } else {

        callback(false);

      }

    });
  });

  request.write(request_body);
  request.end();
}

Deleting an event

Send your delete requests to /v1/events/--uidofyourevent--

Parameters you need to attach in the body of your request are access_token and nonce.

An example in php:

$ch = curl_init("https://api.openagenda.com/v1/events/$eventUid");

curl_setopt($ch, CURLOPT_POSTFIELDS, array(
  'access_token' => $accessToken,
  'nonce' => $nonce,
));

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');

$received_content = curl_exec($ch);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE)==200)
{
  echo 'deletion successfull';
}

Remove location association

To remove any location association to a specific event, send a delete request to the resource /v1/events/--eventuid--/locations/--locationuid--

access_token and nonce parameters are required in the body of the request

Remove specific occurrences

To remove any occurrence by its date and location, send a delete request to the resource /v1/events/--eventuid--/locations/--locationuid--/dates/--date--

The --date-- parameter should follow the format Y-m-d (ex: 2012-08-23)

If you need to remove occurrences starting at a specific time, add /--time-- to your root.

For example: /v1/events/41423142/locations/44325225/dates/2012-08-23/15:00

access_token and nonce parameters are required in the body of the request

Publishing on OpenAgenda - Agendas

You can use the api to reference events in agendas you edit. Two resources are available, one for adding event references to agendas, the other to remove them.

Adding references

Send put or post requests to /v1/agendas/--uidofyouragenda--/events

Parameters required in the body of your request are access_token, nonce, data

The data parameter is a json encoded array with the following key/value pairs:

• event_uid: The uid of the event you want to add to your agenda.
• article: Optional. In case you want to write a little something to stick with the event on your agenda.
• category: An optional category.

Removing references

Send a delete request to /v1/agendas/--uidofyouragenda--/events/--uidoftheevent-- to remove the reference of the event in the agenda.

Well. For now its one complete example.

Publishing on OpenAgenda with php curl

The following php script goes through the process of creating a location, an event with an image, sharing that event to a agenda and finally changing the events image again (why not).

// the long road to publishing data on openagenda.com

// the key is needed to fetch information via the api
$key = '--yourapikey--';

// the secret key is needed to retrieve the access token for writing
$secret = '--yourapisecretkey--';

$url = 'https://api.openagenda.com/v1';

// we use curl to handle the requests and responses
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// this is the resource to get the access token
curl_setopt($ch, CURLOPT_URL, "$url/requestAccessToken");

// the secret goes in the body of the request
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, array('code' => $secret));

$received_content = curl_exec($ch);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) throw new Exception('Could not retrieve token');

// the token is in the response
$response = json_decode($received_content, true);

// when does the token expire?
echo "Token is retrieved: '${response['access_token']}' It will expire in ${response['expires_in']} seconds.\n";

$token = $response['access_token'];

// we either know the location uid, or we don't and we need to create a location. Lets do that now
curl_setopt($ch, CURLOPT_URL, "$url/locations");

// a location needs a name, an address, a longitude and a latitude
$locationData = array(
  'placename' => 'Groundhog Plaza',
  'address' => 'Groundhog Plaza, Punxsutawney, Pennsylvania 15767',
  'latitude' => 40.946097,
  'longitude' => -78.968617
);

// prepare the post
curl_setopt($ch, CURLOPT_POSTFIELDS, array(
  'access_token' => $token,
  'nonce' => $nonce = rand(0, 100000), // the nonce is used once.
  'data' => json_encode($locationData)
));

// fire away
$received_content = curl_exec($ch);

$response = json_decode($received_content, true);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200)
{
  throw new Exception('Could not create location' . ($response !== null?': ' . $response['error_description']:''));
}

// we have our location, we can now proceed to create the event
// we can hold on to this uid to associate more events to the same location later.
$locationUid = $response['uid'];


// we get curl ready for the next post
curl_setopt($ch, CURLOPT_URL, "$url/events");


// Groundhog day is a yearly event.
$eventData = array(
  'title' => array('en' => 'Groundhog Day', 'fr' => 'Le jour de la marmotte'),
  'description' => array('en' => 'When will the winter end? Get up early.', 'fr' => 'Quand finira l\'hiver? Réveillez-vous tôt.'),
  'tags' => array('en' => 'groundhog, fair, tradition, bill murray', 'fr' => 'marmotte, fête foraine'),
  'locations' => array(
    array('uid' => $locationUid, 'dates' => array(
      array('date' => '2014-02-02', 'timeStart' => '07:00', 'timeEnd' => '11:00'),
      array('date' => '2015-02-02', 'timeStart' => '07:00', 'timeEnd' => '11:00'),
      array('date' => '2016-02-02', 'timeStart' => '07:00', 'timeEnd' => '11:00'),
    ))
  )
);

// we want to set an image (not more than 6mb)
$imagePath = '@' . dirname(__FILE__) . '/images/groundhog-day.jpg';

// prepare the post
curl_setopt($ch, CURLOPT_POSTFIELDS, array(
  'access_token' => $token,
  'nonce' => $nonce+1,
  'data' => json_encode($eventData),
  'image' => $imagePath,
  'publish' => true
));

// send the request

$received_content = curl_exec($ch);

$response = json_decode($received_content, true);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200)
{
  throw new Exception('Could not create the event' . ($response !== null?': ' . $response['error_description']:''));
}

// the event is created, the response contains the uid.
$eventUid = $response['uid'];


// there is a agenda to which we want to add the event to, but we don't know its uid.
// We can gets its slug from its url and use that in request to retrieve the uid

curl_setopt($ch, CURLOPT_URL, "$url/agendas/uid/kaore-olafsson?key=$key");

// this is a get request
curl_setopt($ch, CURLOPT_POST, false);

$received_content = curl_exec($ch);

$response = json_decode($received_content, true);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200)
{
  throw new Exception('Could not retrieve the agenda uid' . ($response !== null?': ' . $response['error_description']:''));
}

$agendaUid = $response['data']['uid'];


// now that we have the agenda uid, we can associate the event with it

curl_setopt($ch, CURLOPT_URL, "$url/agendas/$agendaUid/events");

// the data required here is just the uid of the event. Optionally, some editorial content an a category can be added too.

$shareData = array(
  'event_uid' => $eventUid,
  'article' => 'If for some reason I find myself in Pennsylvania in the middle of the winter, well...',
  'category' => 'Folklore'
);

curl_setopt($ch, CURLOPT_POSTFIELDS, array(
  'access_token' => $token,
  'nonce' => $nonce+2,
  'data' => json_encode($shareData),
));

$received_content = curl_exec($ch);

$response = json_decode($received_content, true);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200)
{
  throw new Exception('Could add the event to the agenda' . ($response !== null?': ' . $response['error_description']:''));
}


// for some reason I am not happy with my event image. I want to change it.

curl_setopt($ch, CURLOPT_URL, "$url/events/$eventUid");

curl_setopt($ch, CURLOPT_POSTFIELDS, array(
  'access_token' => $token,
  'nonce' => $nonce+3,
  'image' => '@' . dirname(__FILE__) . '/images/groundhog.jpg'
));

$received_content = curl_exec($ch);

$response = json_decode($received_content, true);

if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200)
{
  throw new Exception('Could change the image' . ($response !== null?': ' . $response['error_description']:''));
}

// It worked.

There.