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:

    en.wikipedia.org/wiki/Textile

    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.

email

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.

Laden...