OpenPoland.net API Documentation Release 1.0 Michał Gryczka July 11, 2014
Contents 1 REST API tokens: 3 1.1 How to get a token............................................ 3 2 REST API : search for assets 5 2.1 How to find specyfic assets........................................ 5 3 REST API : get asset metadata 7 3.1 How to find specyfic assets........................................ 7 4 REST API : get asset data 9 4.1 How to get all data for selected asset.................................. 9 4.2 How to get filtered data for selected asset................................ 10 i
ii
OpenPoland.net API Documentation, Release 1.0 Welcome to OpenPoland REST API documentation. Here you will find all informations you need for developmetn of systems and applications with this API. We hope that this document is helpful for you, but if you have any questions or you ve found mistake or inconsistency, please feel free to contact us at At this moment (beta release) API exposes methods for: listing assets searching metadata retrieval data retrieval Contents 1
OpenPoland.net API Documentation, Release 1.0 2 Contents
CHAPTER 1 REST API tokens: 1.1 How to get a token Once you register at OpenPoland.net you can find your token in settings or at search page in example query. 3
OpenPoland.net API Documentation, Release 1.0 4 Chapter 1. REST API tokens:
CHAPTER 2 REST API : search for assets 2.1 How to find specyfic assets Allowed method: GET Context: /api/list Query params: q (string) : search phrase (optional) page (integer) : page of results (optional) Request search results: curl -i -XGET https://openpoland.net/api/list?q=ludność" -H "Authorization: Token YOUR_TOKEN_HERE Response (HTTP/1.0 200 OK): "has_next" : false, "page" : "1", "results" : "id" : 1342, "title" : "Ludność w wieku przedprodukcyjnym (17 lat i mniej), produkcyjnym i poprodukcyj "id" : 2137, "title" : "Ludność wg grup wieku i płci (NTS-5, 1995-2012)" "id" : 1336, "title" : "Ludność wg miejsca zameldowania/zamieszkania i płci (NTS-5, 1995-2012)" "id" : 2577, "title" : "Ludność w wieku przedprodukcyjnym (14 lat i mniej), produkcyjnym i poprodukcyj "id" : 3361, "title" : "Ludność w wieku przedprodukcyjnym (17 lat i mniej), produkcyjnym i poprodukcyj 5
OpenPoland.net API Documentation, Release 1.0... ] 6 Chapter 2. REST API : search for assets
CHAPTER 3 REST API : get asset metadata For example if you want to find more about asset Ludność zamieszkała w gospodarstwie domowym wg wieku (NTS- 5, 1996) with id 1891, which you found throu search query, you will use metadata method to get more specyfic informations. 3.1 How to find specyfic assets Allowed method: GET Context: /api/assset/asset_id]/meta Parameters: asset_id : string Example request curl -i -XGET -H "Authorization: Token YOUR_TOKEN_HERE " https://openpoland.net/api/asset/1891/me Response (HTTP/1.0 200 OK): "dims" : "values" : "id" : 3703, "name" : "z użytkownikiem gospodarstwa rolnego ponad 1 ha" "id" : 3704, "name" : "z użytkownikiem działki do 1 ha" "name" : "Gospodarstwa" "values" : "id" : 3700, 7
OpenPoland.net API Documentation, Release 1.0 "name" : "Wiek" "name" : "ogółem" "id" : 3701, "name" : "poniżej 15 lat (urodzeni: 13.06.1981r.-12.06.1996r.)" "id" : 3702, "name" : "15 lat i więcej (urodzeni przed 13.06.1981r.)" "values" : "id" : 528, "name" : "ogółem" "id" : 529, "name" : "mężczyźni" "id" : 530, "name" : "kobiety" "name" : "Płeć" "years" : 1996 "subkey" : 1891, "title" : "Ludność zamieszkała w gospodarstwie domowym wg wieku (NTS-5, 1996)" 8 Chapter 3. REST API : get asset metadata
CHAPTER 4 REST API : get asset data Limits and paging: The volume of some assets data may be as large as 400MB or even larger. Thus API limits the size of returned data for each query and data is paged, you can request next page of results using query parameter. If you need higher data limits, please contact us at contact@openpoland.net. 4.1 How to get all data for selected asset Allowed method: GET Context: /api/assset/asset_id]/data Parameters: asset_id : string Response structure: Record of results array has the following structure: first field is always NTS id of territorial unit second field is always common name of territorial unit then N (from 1 to 5) fields follow containing values for dimensions specified by metadata last four fields are always (in order) year, measure unit, value, data attribute Example request curl -i https://openpoland.net/api/asset/1891/data/ -XGET -H "Authorization: Token YOUR_TOKEN_HER Response (HTTP/1.0 200 OK): "asset_id" : "1891", "has_next" : true, "page" : 0, "results" : "1101506022", "Andrespol (2)", "z użytkownikiem gospodarstwa rolnego ponad 1 ha", 9
OpenPoland.net API Documentation, Release 1.0 ] ] "1996", 802.0, "1101506022", "Andrespol (2)", "z użytkownikiem gospodarstwa rolnego ponad 1 ha", "mężczyźni", "1996", 386.0, "1101506022", "Andrespol (2)", "z użytkownikiem gospodarstwa rolnego ponad 1 ha", "kobiety", "1996", 416.0, "1101506022", "Andrespol (2)", "z użytkownikiem gospodarstwa rolnego ponad 1 ha", "poniżej 15 lat (urodzeni: 13.06.1981r.-12.06.1996r.)", "1996", 153.0, "1101506022", "Andrespol (2)", "z użytkownikiem gospodarstwa rolnego ponad 1 ha", "poniżej 15 lat (urodzeni: 13.06.1981r.-12.06.1996r.)", "mężczyźni", "1996", 72.0, 4.2 How to get filtered data for selected asset Allowed method: POST 10 Chapter 4. REST API : get asset data
OpenPoland.net API Documentation, Release 1.0 Context: /api/assset/asset_id]/data_filter Data format (json): Example request curl -XPOST https://openpoland.net/api/asset/2888/data_filter \ -d "query": "time" :1998 "nts" : 4326562000] \ -H "Content-Type: application/json"\ -H Authorization: Token YOUR_TOKEN_HERE Response (HTTP/1.0 200 OK): "asset_id" : "2577", "has_next" : true, "page" : 15, "results" : "2245068000", "Powiat m.jaworzno", "w wieku poprodukcyjnym", "kobiety", "2008", 10843.0, "2245075000", "Powiat m.sosnowiec", "2008", 221259.0, "2245075000", "Powiat m.sosnowiec", "mężczyźni", "2008", 104983.0, "2245075000", "Powiat m.sosnowiec", "kobiety", "2008", 4.2. How to get filtered data for selected asset 11
OpenPoland.net API Documentation, Release 1.0 ] ] 116276.0, 12 Chapter 4. REST API : get asset data