Sections

DataCollector

API

Sample code

Scores

Scores are the periodic assessment values given to indicators.

Create

POST /scores.xml
POST /indicators/#{indicator_id}/scores.xml

Creates a new score for an indicator. A score is an assessment value for the indicator in a given period of time. When creating a score you must provide a value property which can contain float values and optionally you may provide a date property. If no date property is provided it assumes the current date in UTC time zone.

The format to use for the date property is: YYYY-MM-DD. For example:

<score>
  <value>99.98</value>
  <date>2010-08-28</date>
</score>

The date property value marks the end of a period. Based on the frequency value of the indicator the exact start- and end-dates of this period are determined. For example, if the frequency of the indicator is set to Month, and you submit a score with date 2010-08-20, then this will result in a start-at value of 2010-08-01 and an end-at value of 2010-08-31.

The one exception is when the indicator has no frequency value. In that case instead of providing a date property value you must provide both start-at and end-at property values.

If you try to create a score for a period that already has a score you will get an HTTP 409 status code as response.

Request

curl -u TOKEN:x -X POST -H "Content-Type: application/xml; charset=utf-8" \
  -d "<score><value>99.83</value><date>2010-08-26</date></score>" \
  https://dashboard.kpilibrary.com/api/v2/indicators/INDICATOR_ID/scores.xml

Response

Status: 201
Location: https://dashboard.kpilibrary.com/api/v2/scores/NEW_SCORE_ID.xml

<?xml version="1.0" encoding="UTF-8"?>
<score>
  <id type="integer">NEW_SCORE_ID</id>
</score>

Note that if you post to /scores.xml you must provide an indicator_id. Either as part of the URL (e.g. https://dashboard.kpilibrary.com/api/v2/scores.xml?indicator_id=93839) or within the body that is submitted. For example:

<score>
  <indicator-id>93839</indicator-id>
  <value>99.98</value>
  <date>2010-08-28</date>
</score>

Upsert

POST /scores/upsert.xml
POST /indicators/#{indicator_id}/scores/upsert.xml

Upserts a score with a new value.

If there’s no known score for the period given then a new score will be created. On success the response will be an HTTP 201 status code and the response body will contain the id of the new score.

Otherwise the existing score will be updated. On success the response will be an HTTP 200 status code and the response body will be empty.

Request

curl -u TOKEN:x -X POST -H "Content-Type: application/xml; charset=utf-8" \
  -d "<score><indicator-id>93839</indicator-id><value>99.3</value></score>" \
  https://dashboard.kpilibrary.com/api/v2/scores/upsert.xml

Response

Status: 200

MUpsert

POST /scores/mupsert.xml

Upserts multiple scores with new values. Currently a maximum of 100 scores can be submitted with this method.

If no date property is provided for a score element it assumes the current date in UTC time zone.

If there’s no known score for the indicator and period given then a new score will be created, otherwise the existing score will be updated with the given new value. On success the response will be an HTTP 200 status code and the response body will be empty.

Request

curl -u TOKEN:x -X POST -H "Content-Type: application/xml; charset=utf-8" \
  -d "<scores type='array'><score><indicator-id>93839</indicator-id><value>99.3</value></score><score><indicator-id>93840</indicator-id><date>2011-08-28</date><value>198</value></score></scores>" \
  https://dashboard.kpilibrary.com/api/v2/scores/mupsert.xml

Response

Status: 200

Update

PUT /scores/#{id}.xml

Updates an existing score with a new value.

Request

curl -u TOKEN:x -X PUT -H "Content-Type: application/xml; charset=utf-8" \
  -d "<score><value>99.3</value></score>" \
  https://dashboard.kpilibrary.com/api/v2/scores/SCORE_ID.xml

Response

Status: 200

Delete

DELETE /scores/#{id}.xml

Destroys a single score

Request

curl -u TOKEN:x -X DELETE \
  https://dashboard.kpilibrary.com/api/v2/scores/SCORE_ID.xml

Response

Status: 200

Show

GET /scores/#{id}.xml

Returns a single score.

Request

curl -u TOKEN:x -X GET https://dashboard.kpilibrary.com/api/v2/scores/SCORE_ID.xml

Response

Status: 200

<?xml version="1.0" encoding="UTF-8"?>
<score>
  <id type="integer">92398</id>
  <value type="float">88.0</value>
  <start-at type="date">2010-04-01</start-at>
  <end-at type="date">2010-06-30</end-at>
  <period>Q2 2010</period>
  <indicator-id type="integer">128</indicator-id>
</score>

List

GET /indicators/#{indicator_id}/scores.xml

Returns the scores of a single indicator, sorted by date in descending order.

By default it returns a maximum of 100 scores per request. By using the per_page parameter a maximum of 1000 scores per request can be returned.

Request

curl -u TOKEN:x -X GET \
  https://dashboard.kpilibrary.com/api/v2/indicators/INDICATOR_ID/scores.xml

Response

Status: 200

<?xml version="1.0" encoding="UTF-8"?>
<scores type="array">
  <score>
    <id type="integer">30229</id>
    <value type="float">99.0</value>
    <start-at type="date">2010-06-01</start-at>
    <end-at type="date">2010-06-30</end-at>
    <period>Jun 2010</period>
  </score>
  <score>
    <id type="integer">29372</id>
    <value type="float">99.2</value>
    <start-at type="date">2010-05-01</start-at>
    <end-at type="date">2010-05-31</end-at>
    <period>May 2010</period>
  </score>
</scores>