Navigation

Version 1.0: Technical documentation

API version 1.0
Last modified 2010-07-19

The API consists of three types of resources which are made available:

  • Index page, which provides a listing of all available meetings and and allows discoverability of the available resources.
  • Metadata for each recorded council meeting which contains information about the meeting, participants, agenda and the video recording.
  • Video recordings, which are available through HTTP and RTMP protocols.

The resources form the following conceptual hierarchy

_images/data_hierarchy.png

The index page is available from a static URL at

http://www.helsinkikanava.fi/@@opendata-index-v1.0

all the other resources are discoverable by following the information in the index page.

Data formats

The information in the index page and the metadata for the meetings is encoded using the JSON data-interchange format. Please refer to the sections below for the structure and semantics of the particular resources. The HTTP resources support also JSONP for making cross-domain requests. JSONP requests should include a callback parameter that specifies the name of the method call the JSON data will be wrapped in. For example, the index page could be requested as

http://www.helsinkikanava.fi/@@opendata-index-v1.0?callback=myCallback

when making a JSONP request.

The video recordings are encoded using the H.264 codec and the audio streams are encoded as MP3 streams. The videos are served using the MP4 format.

Index page

The index page contains information about all the available council meeting recordings. It is defined by a JSON schema available at

http://www.helsinkikanava.fi/@@opendata-index-schema-v1.0

and has the following kind of structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "version": "1.0",
  "sessions": [
      {
          "title": "Council meeting 12.4.2010",
          "url": "http://www.helsinkikanava.fi/kaupunginvaltuusto\/council-meeting\/@@opendata-session-v1.0"
      },
      {
          "title": "Council meeting 15.2.2010",
          "url": "http://www.helsinkikanava.fi/kaupunginvaltuusto\/council-meeting-2\/@@opendata-session-v1.0"
      }
  ]
}

The example above describes two distinct council meetings. The index page may contain any number of entries that are available at a given time. The semantics of the items are described below.

Key Type Purpose
version string Version of the specification this resource complies with
sessions[] list List of available sessions. May contain an arbitrary number of sessions.
sessions[].title string Human-readable title describing the council meeting
sessions[].url URL URL to the JSON encoded metadata resource for the meeting

The index page is available from a static URL at

http://www.helsinkikanava.fi/@@opendata-index-v1.0

Metadata

The metadata resource describes a council meeting in detail including the following information:

  • Start and finish times
  • Agenda
  • List of participants
  • Voting results
  • Resolutions
  • Statement timings
  • Video location

The document is defined by a JSON schema available at

http://www.helsinkikanava.fi/@@opendata-session-schema-v1.0

and has the following kind of structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
    "version": "1.0",
    "id": "6be9a6c445d7615acf5e37a4e551f23a",
    "started": "2010-07-12T12:52:59+03:00",
    "finished": "2010-07-12T16:52:59+03:00",
    "title": "Council meeting",
    "session_url": "http:\/\/www.helsinkikanava.fi\/kaupunginvaltuusto\/council-meeting",
    "video": {
        "mimetype": "video\/mp4",
        "height": 288,
        "width": 512,
        "http_url": "http:\/\/media.helsinkanava.fi\/valtuusto230610.mp4",
        "screenshot_url": "http:\/\/www.helsinkanava.fi\/kaupunginvaltuusto\/council-meeting\/screenshot.jpg",
        "rtmp": {
            "server_url": "rtmp:\/\/media.helsinkanava.fi\/hki",
            "video_id": "councilmeeting.mp4"
            }
    },
    "attendance": [
        {
            "name": "John Doe",
            "party": "Vihre\u00e4t",
            "seat": "076"
        }
    ],
    "issues": [
        {
            "id": 1,
            "resolution": "Nulla id massa lorem",
            "statements": [
                {
                    "allocated_time": 480,
                    "participant": {
                        "name": "John Doe",
                        "party": "Vihre\u00e4t",
                        "seat": "076"
                        },
                    "duration": 635,
                    "finished": "2010-07-12T12:52:59+03:00",
                    "started": "2010-07-12T12:52:59+03:00",
                    "video_position": 11056
                }
            ],
            "timestamp": "2010-07-12T12:52:59+03:00",
            "title": "Aenean ac mattis ante",
            "video_position": 8868,
            "votes": [
                {
                    "against_title": "Lipsum lorem",
                    "finished": "2010-07-12T12:52:59+03:00",
                    "for_title": "Lorem lipsum",
                    "results": {
                        "absent": 4,
                        "against": 3,
                        "empty": 0,
                        "for": 34
                    },
                    "started": "2010-07-12T12:52:59+03:00",
                    "type": "normaali"
                }
            ]
        }
    ]
}

The example above describes a single council meeting. The semantics of the items are described below. For a normative reference please refer to the JSON schema definition.

Note

For council meetings before 2010 some of the described fields may contain empty values if the data was not available when the recording was made.

Key Type Purpose
version string Version of the specification this resource complies with.
id string Identifier for meeting described by the resource. This is guaranteed to be unique among meetings.
started timestamp Time when the meeting started, ISO8601 formatted.
finished timestamp Time when the meeting finished, ISO8601 formatted.
title string Human readable title for the meeting.
url URL URL to the video page on the Helsinki-kanava main site corresponding to this meeting.
video.mimetype string Mimetype of the video file.
video.height integer Height of the video in pixels.
video.width integer Width of the video in pixels.
video.http_url URL URL of the video file for HTTP use.
video.screenshot_url URL URL of a screenshot of the video. The image has the same dimensions as the video.
video.rtmp.netconnection_url URL The NetConnection URL for the RTMP server.
video.rtmp.video_id string The video identifier for the RTMP server.
attendance[] list List of participants that have been present during the meeting.
attendance[].name string Name of the participant.
attendance[].party string Political party of the participant. May be empty.
attendance[].seat string Identifier of the seat used by the participant.
issues[] list List of issues on the agenda. The list may contain an arbitrary number of objects.
issues[].id integer Identifier of the issue.
issues[].timestamp timestamp Time when the processing of the issue started, ISO8601 formatted.
issues[].title string Human readable title of the issue.
issues[].video_position integer Position on the video when the processing of the issue started, given in seconds from the beginning of the video.
issues[].resolution string Resolution of the issue.
issues[].statements[] list List of statements made by the participants during the processing of the issue. The list may contain an arbitrary number of statements.
issues[].statements[].allocated_time integer Amount of time allocated for the participant to make the statement. The value is given in seconds.
issues[].statements[].participant.name string Name of the participant making the statement.
issues[].statements[].participant.party string Political party of the participant making the statement. May be empty.
issues[].statements[].participant.seat string Identifier of the seat used by the participant making the statement.
issues[].statements[].duration integer Actual amount of time used by the participant to make the statement. The value is given in seconds.
issues[].statements[].started timestamp Time when the statement started, ISO8601 formatted.
issues[].statements[].finished timestamp Time when the statement finished, ISO8601 formatted.
issues[].statements[].video_position integer Position on the video. Given in seconds from the beginning of the video.
issues[].votes[] list List of votes cast during the processing of the session. The list may contain an arbitrary number of voting results.
issues[].votes[].started timestamp Time when the voting started, ISO8601 formatted.
issues[].votes[].finished timestamp Time when the voting finished, ISO8601 formatted.
issues[].votes[].for_title string Title for the for-vote.
issues[].votes[].against_title string Title for the against-vote.
issues[].votes[].type string The type of the voting, either open or closed.
issues[].votes[].results.for integer Number of for-votes.
issues[].votes[].results.against integer Number of against-votes.
issues[].votes[].results.absent integer Number of absent participants in this voting.
issues[].votes[].results.empty integer Number of empty votes.

Video recordings

The videos are available using two different protocols: RTMP and HTTP. The RTMP protocol allows the videos to the streamed arbitrarily but requires a video player component that supports the protocol.

Table Of Contents

Previous topic

Contact information

Next topic

Version 2.0: Technical documentation

This Page

Navigation

© Copyright 2010-2011, Helsingin kaupunki. Created using Sphinx 1.0.4.