Ikdoe API
The Ikdoe API is basically a standard RESTful API, with the resources Activities and Locations. We will document this some further later on, but wikipedia already does quite a good job documenting a standard RESTful API at:
en.wikipedia.org/wiki/Representational_State_Transfer#RESTful_web_services
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.
About Activity and Location ids
Besides our own ID‘s we will support the possibility of assigning custom ID‘s to activities and locations. This way our partners can use their own ID‘s and still can uniquely identify activities and locations in the Ikdoe database. We will call this ID reference id. Using these id‘s works like this:
- You can assign a reference_id on create and update. To do this you can pass an integer to the field reference_id. Each of our partners can have one reference_id per location and activity. reference_id_type (e.g. whether it is a Hyves reference id) will be determined by the account used to access our API.
- On output your reference_id will be given by this reference_id field.
- Actions on our API that require an ID to identify the resource (show,
update), support supplying not only our id, but also your
reference_id. This allows us to keep a nice RESTful API, and still
allow our partners to uniquely address any resource using their own
ID‘s. When using a reference_id, the id is prefixed with the
reference_id_type.
Example Given an activity with an Ikdoe ID 1234 and a hyves reference_id 4567. Instead of updating this activity by doing a PUT to ikdoe.nl/activities/1234 you can also do a PUT to: ikdoe.nl/activities/Hyves:4567
Searching for activities
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-id" |
| 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 |
| updated_since: | String formatted YYYY-MM-DD HH:MM:SS. Handy when using Ikdoe as a Feed |
| created_since: | String formatted YYYY-MM-DD HH:MM:SS. Handy when using Ikdoe as a Feed |
| sorted_by: | Default is sorted by next future occurrence. Other options are: "sorted_by_created", "sorted_by_relevance" |
| page: | Integer |
| per_page: | Integer |
Data structure
There are some minor differences between the datastructure as shown in output (e.g. when Ikdoe sends an activity to an external API like that of Hyves, or when you search using our API) and the datastructure as expected in input (e.g. when you post an activity to the Ikdoe API). There are some fields that only exist on input or only exist on output. In this overview these will be marked as +input only+ or +output only+.
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.
Activity:
id (output only, required)
| status (output only, required): | An activity can have several status codes:
We supply the inactive activities (double, deleted, cancelled) so you can easily maintain a up-to-date database for yourself:) |
| 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-id* (required): | The id of the category this event is in. At this moment we have the
following categories:
We will make the available categories available through an API call. If desired we can include a category_name field available in output of activities. |
| location_attributes/location_id (required): | In our output we we always nest all location fields (see further in this document) under location. When sending an activity to our API, you can either include all location fields under location_attributes, or specify a location_id. |
| website: | The website of this event. |
| copyright_source_url (output only): | 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. |
| periods_attributes (one required): | An array containing one or more Periods. See the datastructure of Period further down this document. |
| tags_array: | An array containing strings. Specifies the tags associated with this event. |
| images_attributes: | An array containing 0 or more Images. See the datastructure of Image further down this document. |
Location
| 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. |
| website: | The website of this location. |
| copyright_source_url (input only): | The website used as source for this activity. This helps our spiders avoid duplication. Due the copyright law you must include this link on your webpage when showing a location. |
| images_attributes: | An array containing 0 or more Images. See the datastructure of Image further down this document. |
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). |
| day_period: | An integer describing when this event takes place. +start_time/end_time+
have precedence over day_period.
|
Image
| image (input only, required): | The actual binary image, when sending a MIME multipart message. |
| image_url (output only): | A full url where the image can be found. This will be an url under ikdoe.nl. |