diff --git a/README.rst b/README.rst deleted file mode 100644 index 06940c9..0000000 --- a/README.rst +++ /dev/null @@ -1,364 +0,0 @@ -Kolada API -========== - -`Kolada `_ provides a web-service for accessing -standardized `key performance indicators -`_ (KPI) -concerning Swedish municipalities and organizational units. The -database is created and upheld by `RKA `_ This -project describes that API and includes examples for accessing it. - - -The kolada database --------------------- - -Within the kolada database there are two different types of data. - -* The municipal data -* The organizational unit data - -The municipal data contains KPIs for the Swedish kommuner and -landsting, there are about 4500 KPIs within the database. On -organizational unit level the data is less comprehensive, but there -are still quite a few KPIs on this level. Each KPI is currently -measured once a year, and the data may be divided by gender. I.e. for -each KPI there may be at most three values, based on gender being -female, male and a total. - -The general structure of the data is:: - - KPI, municipal or organizational unit, year, gender: data - -In other words, the database has only four basic dimension for each -dataset. - -To help client make relevant queries, there are two help-dimensions, -KPI groups and Municipal groups. The KPI groups consists of the groups -that RKA have chosen to publish as 'Tabeller' (Jämföraren) on `kolada `_. - -The municipal groups are groups present in koladas various -reports. Data is also present for each municipal group, this value is -an unweighted average of the members. - - -Below is a technical information about the URL:s in koladas Web -API. If you know swedish you may also be interested in the examples folder, -e.g `kommunens kvalitet i korthet `_ - - - -Technical information about data and metadata ---------------------------------------------- - -Key performance indicator values are referred to as **data** whereas **metadata** describes - -* Key performance indicator -* Municipality -* Organizational unit (OU) - -For a proper query URL you need metadata such as id of a KPI and municipality or organizational unit. See the examples below. -For each query the result is - -* in **JSON** format -* limited to 5000 items for each request - -Note! To read all entries for a query you need to retrieve each page by following the URL in the **next_page** field, see the -Routes section for more information. - -Routes ------- - -The service is found at **api.kolada.se/v2/...** and provides a -read only API. Each response from the service -if it's correct returns a JSON structure like:: - - { - "values": [ {obj}, {obj}, ..., {obj}], - "count": , // Length of values - "previous_page": "", // Optional: Full URL to previous page, if any - "next_page": "" // Optional: Full URL to next page, if any - } - -The **obj** structure differs between metadata, find out in -the below section what it looks like for each. - -For all URL:s a parameter *per_page* may be given, which will limit -the number of posts in the result. The default value is the -maximum, 5000. - -Metadata --------- - -For each query remember to `url-encode -`_ the SEARCH_STR. - -All metadata may be queried on the form - - * entity/id - * entity?title=... - -where entity may be - - * kpi - * kpi_groups - * municipality - * municipality_groups - * ou - -The id may be a comma separated string of many ids. - - -Examples -________ - -KPI - * SEARCH_STR = Män som tar ut tillfällig föräldrapenning - - ``_ - -Object structure:: - - { - "auspices": "", - "id": "", - "title": "", - "description": "", - "definition": "", - "municipality_type": "L|K|A", - "is_divided_by_gender": , - "operating_area": "", - "ou_publication_date": "" or null, - "perspective": "", - "publication_date": "" or null, - "has_ou_data": , - "prel_publication_date": "" or null - } - - -Here: - -* publication_date and prel_publication_date is the expected next - publication or preliminary publication of the KPI on - municipality-level. - -* ou_publication_date is the date of the next publication of the KPI - on OU-level. - -* is_divided_by_gender is a hint that there may be data on all genders. - -* municipality_type is either L (for County Council `(swedish: - Landsting)`) or K for municipality `(swedish: Kommun)`. A is short - for a kpi where values for both K and L may exists. - -* auspices and operating_area are metadata on the KPI. - -* has_ou_data indicates whether there may exist data on the OU-level. - - -In the structure above, there are several dates that are given as -strings. The typical structure of the date is the standard swedish: -YYYY-mm-dd, but there are no technical constraints for this pattern. - - - -Municipality - * SEARCH_STR = lund - - ``_ - -Object structure:: - - { - "id": "", - "title": "", - "type": "L|K" - } - -type - - **L** is short for County Council `(swedish: Landsting)` - - **K** is short for municipality `(swedish: Kommun)` - - - - -Organizational units -_____________________ - - -Example: - * SEARCH_STR = skola - - ``_ - -Object structure:: - - { - "id": "", - "municipality": "", - "title": "" - } - -you may optionally give a municipality as a parameter, e.g.: - - ``_ - -which will return all OUs from municipal 'Upplands Väsby', where -'skola' is part of the title. The municipality paramter may be a -comma-separated string of many municipalities. - - - -Groups -_______ - -There a two types of groups defined by the by the API, - - * KPI groups - * Municipality groups - -Example: - * SEARCH_STR = kostnad - - ``_ - -Object structure:: - - { - "id": "", - "title": "", - "members": [ - {"id": "", "title": ""} - ... - ] - } - - - -Query data ----------- - -Data queries are on the following forms, the form where all entities are given: - -/v2/data/kpi//municipality//year/ - -Here, the MUNICIPALITY_ID may be that of a group. - - Example: http://api.kolada.se/v2/data/kpi/N00945/municipality/1860/year/2009,2007 - - * Note! KPI, MUNICIPALITY_ID and PERIOD can all be comma separated strings. The URL length is the limit which differs across browsers. - - -or where only two are given: - -/v2/data/kpi//year/ - Example: http://api.kolada.se/v2/data/kpi/N00945/year/2009 - -/v2/data/kpi//municipality/ - Example: http://api.kolada.se/v2/data/kpi/N00945/municipality/1860 - -/v2/data/municipality//year/ - Example: http://api.kolada.se/v2/data/municipality/1860/year/2009 - - -Object structure:: - - { - "kpi": "", - "municipality": "", - "period": "", - "values: [ - {"count": , "gender": "T|K|F", "status": "", "value": or null} - ... - ] - } - -The values array may at most contain three entries, one for each -gender. 'count' we only differ from 1 when the municipality is a -group. In this case the count will be the number of members in that -group which contributed to the value, which is an unweighted average. - - -For the organizational unit level, this are exacly the same as above -except we are working with ou instead of municipality. - -/v2/oudata/kpi//ou//year/ - * Example: http://api.kolada.se/v2/oudata/kpi/N15033/ou/V15E144001301/year/2009,2007 - * Example with multiple KPI's and OU_ID's http://api.kolada.se/v2/oudata/kpi/N15033,N15030/ou/V15E144001301,V15E144001101/year/2009,2008,2007 - -/v2/oudata/kpi//year/ - Example: http://api.kolada.se/v2/oudata/kpi/N15033/year/2007 - -/v1/oudata/kpi/ - Example: http://api.kolada.se/v2/oudata/kpi/N15033/ou/V15E144001301 - -/v1/oudata/ou/ - Example: http://api.kolada.se/v2/oudata/ou/V15E144001301/year/2007 - - - -Object structure:: - - { - "kpi": "", - "out": "", - "period": "", - "values": [ - {"count": , "gender": "T|K|F", "status": "", "value": or null}, - ... - ] - } - - -New, deleted or changd values ------------------------------- - -All data-queries has a optional extraparameter *from_date*. This -parameter notifies the API that the last time you made *the exact same -query* was at this perticular date, and you want the changes since -then. - -**OBS!** The from_date parameter works only on data-queries, and will not -work on entity-queries. - -When the from_date parameter is given all objects in the values array are returned with an extra-parameter **is_deleted**. - -Object structure:: - - { - "kpi": "", - "out": "", - "period": "", - "values": [ - {"count": , "gender": "T|K|F", "status": "", "value": or null, "is_deleted": 0|1}, - ... - ] - } - -When is_deleted is set the value will always be null. - -The format of the from_date parameter is standard swedish date format: YYYY-MM-DD. - -Example:: - - http://api.kolada.se/v2/data/municipality/1860/year/2009?from_date=2015-02-28 - -Here we ask for changes made to data in this request from 2015-02-28. - - - - -Error-codes ------------ - -Since this is a read-only API, and not a very strict one, there are -not many error you can encounter. But the following may happen - -* HTTP 404 - the url requested did not match any of the URLs described above. -* HTTP 400 - Typically some or many of the paramaters given in the - URL, were illegal. But a too long URL also generates a HTTP 400 - error. -* HTTP 500 - There are some error which will generate a - 500-code. Typically if you encounter this is should be reported to - RKA. - -