OpenAgenda offers an API REST to allow you to read and publish event content programmatically.
Before starting to use it, make sure you have an activated OpenAgenda account. You'll find access keys needed to use the API in your profile settings page
The API allows you to read event data of the platform. All publicly published event data is available under an open data license
To start reading data you'll first need to retrieve the public key associated with your OpenAgenda account, in your account settings page.
Note: If you need to fetch event data specific to certain agendas, it is strongly recommended you use the exports available on said agenda pages. Available data formats are: json, csv, xlsx, ics, rss or pdf.
To fetch event data not specific to certain agendas, first request the activation of transverse fetch features by sending a mail to email@example.com by specifying the email of your account as well as some info on your use case.
Once the feature is activated, proceed by following the authentication steps detailed in the next section.
Writing and editing content
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.0standard: 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: firstname.lastname@example.org
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 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 optionally, register your newly created event to one of your agendas by following the agendas section