Ikdoe API
The Ikdoe API is a RESTful API. Since ikdoe is all about activities, the only resource we provide through this api is the activity resource. At the moment we only support XML as response format, but might support additional formats in the future.
Authentication
For authentication, we use HTTP basic authentication, and our partners will get accounts which are authorized for API access. Because HTTP basic authentication over HTTP sends credentials in plain text in a HTTP header, we only allow accessing the API over TLS.
Searching for activities
Besides using the feed it is also possible to perform arbritary searches on our database. Use a HTTP GET on the following url to do that:
https://www.ikdoe.nl/activities.xml
You can use the following set of parameters when searching for activities:
| keyword | The search keywords |
| category_id | An array or string with the category_id / category_ids, see below “Data structure - Activity - category“ |
| category_name | An array or string with the category_name / category_names, see below “Data structure - Activity - category“ |
| start_date | A date string formatted YYYY-MM-DD |
| end_date | A date string formatted YYYY-MM-DD |
| city_name | A city in The Netherlands |
| range | Integer, range around the city in km’s |
| province_name | A province in The Netherlands |
| page | Integer |
| per_page | Integer |
To make the process of creating a valid search url easier, you can just use the normal ikdoe site, and, once you have the desired search results on the search page, insert the .xml into the url.
creating/updating activities
We like to keep our database only loosly coupled with those of our partners. When our parners insert items, we would like to decide ourselves what to do with it: add them, or maybe merge or reject activities where necesary. Often we only want to use parts of the information that is provider. That why we use a single action for partners that want to either add or update activities: create. When updating, just use create and we will figure out which activity you’re talking about and combine the information you provide us, and the information we already have. We will return a xml structure with the resulting activity. To do a create, do a HTTP POST on the following URL:
https://www.ikdoe.nl/activities.xml
As parameters pass an activity parameter which nests the attributes mentioned in the +Data structure+ section. The input parameters can be passed as either one of the following:
| xml (recommended) | Pass the activity data structure as xml in the body of the HTTP POST, and make sure the Content-Type is set to ‘application/xml’. |
| *url encoded* | Pass the activity data url encoded. when using this option, you should set the Content-Type to ’’. The reason for this is, that having the Content-Type ‘application/x-www-form-urlencoded’ will trigger our cross request forgery protection, since it is the type of request that can be done by a webbrowser. Having the Content-Type an empty string, will cause the api to treat the data as url_encoded data without have the CRF protection active. |
Example
To create an activity using curl:
curl --basic -X POST -d '
<activity>
<name>The White Stripes</name>
<content>Live and kicking</content>
<category>Optredens</category>
<website>www.whitestripes.com</website>
<location_attributes>
<name>Ikdoe HQ</name>
<address>Hertzogweg 2 t/m 8</address>
<postal_code>7551 HE</postal_code>
<city_name>Hengelo Ov</city_name>
</location_attributes>
<periods_attributes type="array">
<period>
<date>2011-08-16</date><start_time>17:00</start_time>
</period>
</periods_attributes>
<images_attributes type="array">
<image>
<remote_image_url>http://www.kinkfm.com/images/image/The_White_Stripes.jpg</remote_image_url>
</image>
</images_attributes>
</activity>
' https://email:password@www.ikdoe.nl/activities.xml -H 'Content-Type: application/xml'
Note: use url encoding for the email since normal “@” characters are not allowed. An “@” = “%40“
Data structure
The xml results of both the +changed feed+ and the +activities search api+ will have activities as root node, with the following attributes:
| current_page | The current page of results as given using the page parameter. |
| per_page | The numer of results per page (defaults to 10 for the +activities search api+, and 100 for the +changed feed+) |
| total_pages | The total number of pages in the result set. |
| total_entries | The total number of activities in the result set. |
General information for all the datastructures:
for numbers: a dot (’.’) should be used as decimal seperator.
for urls: should be given as a full url including protocol.
content fields: all memo fields support markup through textile, see:
Any html specified in any of the fields will be escaped, the only proper way to add markup is through textile.
There are slight differences between the datastructures used for output (the feeds or +activities search+), or input (the +create activity api+). Note the +input only+ and +output only+ text after attribute names.
Activity:
| id (output only, required) | A unique number we use to identify this activity. To be able to track updates to this activity later on, you should store this id somewhere in your database. |
| status (output only, required) | An activity can have several status codes. These status codes are for our internal use, so we will always only supply activities with the status active |
| name (required) | A string containing the name of the activity. |
| content (required) | A text field containing a description of the activity. |
| price | The price of the event. If the event is free the value of price will be ‘0’. If the price is unknown this field won’t be given. |
| category (required) | The name of the category this event is in. At this moment we have the following categories: # Optredens # Uitgaan # Festivals # Theater # Sportief # Natuur # Expositie # Educatief # Overig |
| location_attributes (input)/location (output) (required) | In our output we we always nest all location fields (see further in this document) under location. |
| website | The website of this event. |
Contact email for this event. | |
| phone | Contact phone for this event. |
| permalink | The url of the activity on the ikdoe website. |
| copyright_source_url | The website containing the content of the copyright source. Due the copyright law you must include this link on your webpage when showing an activity. |
| copyright_source | The name of the website contenting the content of the copyright source. Can be used to make give the link to copyright_source_url a shorter text. |
| copyright_source_logo | An url pointing to the logo that has to be displayed together with the copyright_source_url |
| periods_attributes (input)/periods (output) (at least one required) | An array containing one or more Periods. See the datastructure of Period further down this document. |
| tags_array/tags_string | An array containing strings. Specifies the tags associated with this event. For output we use tags_array, for input we expect tags_string, a comma seperated string containing all the tags. |
| images_attributes (input)/images (output) (required) | An array containing 0 or more Images. See the datastructure of Image further down this document. |
| spider_id (input only) | To help us find which activity you’re talking about when updating activities through a create action, please specify a spider_id. Spider ids should be unique for each activity and start with your company name, followed with a colon. They are named spider_id because we use the same system for helping our spiders recognize duplicates. So if you’re e.g. Hyves, and you have an activity which you have given an id 123456, you should specify as spider_id ‘Hyves:123456’ whenever you create or update this activity. |
Location
| id (output only, required) | A unique number we use to identify this location. To be able to track updates to this location later on, you should store this id somewhere in your database. |
| name (required) | The name of this location. |
| content | A description of this location. |
| address | String containing street name and number. |
| postal_code | String containing the postal code. |
| city_name (required) | String containing the name of the city. |
| lat (output only) | A double containing the latitude of this location. |
| lng (output only) | A double containing the longitude of this location. |
Period
| date (required) | A date given in the format YYYY-MM-DD. |
| start_time | A time given in the format HH:MM (24 hour clock). |
| end_time | A time given in the format HH:MM (24 hour clock). |
Image
| remote_image_url | output: A full url where the image can be found. This will be an url under www.ikdoe.nl. input: A full url where we can download the image. |
| image_source_url | The url to the source page of the image. Due to the copyright rules you must redirect a visitor to the image_source_url when the visitor wants a larger version. If given as input, we will redirect users to this url when the visitor requests a larger version of the image. |
Changed feed
This action can be used to obtain a list of all the activities that have been added or updated in the given timeframe. This feed can be obtained using a HTTP GET on the following URL:
https://www.ikdoe.nl/activities/changed.xml
Example:
https://www.ikdoe.nl/activities/changed.xml?updated_since=2010-10-6%2010:00&updated_till=2010-10-6%2010:05&page=1
| updated_since | The date/time since which the activities should have been updated or created. This date/time should be specified in the format:
<year>-<month>-<day> <hour>:<minute>[:<seconds>]
|
| updated_till | The date/time untill which the activities should have been updated or created. |
| page | The result list will be paginated (100 entries / page). Use this parameter to specify which page to check. |
will show the first page with all changes between 10:00 and 10:05 on november 6th.
See the section on data structure for information on the xml structure of this feed.