API documentation
Description of API
Description of API version 4
Data exchange between client (Android/iOS) and server is carried outthrough HTTPS protocol. Search bydata uses theelasticsearch technology. When requesting, the parameters are passed by HTTPS protocol and by GET method in the following format:
/api/v4/dataset?source={Query in Json Object}
/api/v4/dataset/version?source={Query in Json Object}
This request performs search as per dataset, and at the same time the source parameter is transferred which describes in what way shall the search and filtration be executed.
/api/v4/mapping/dataset
/api/v4/mapping/dataset/version
This request describes the fields of records used in the dataset
Server response returns in JSON format.It contains data sample or a message about error.
Below are the examples of queries.
Example 1:
Show the description of the fields with their types and structure, as well as a set of versions.
To get the list of fields and types thereof, please make the request indicated below:
The request looks as follows:
/api/v4/mapping/astana_kalasynyn_kylmystyk_kuk1
Response:
{
"astana_kalasynyn_kylmystyk_kuk1" : {
"mappings" : {
"v1" : {
"properties" : {
"city_code" : {
"type" : "string",
"store" : true
},
"crime_code" : {
"type" : "string",
"store" : true
},
"dat_sover" : {
"type" : "string",
"store" : true
},
"hard_code" : {
"type" : "string",
"store" : true
},
"home_number" : {
"type" : "string",
"store" : true
},
"latitude" : {
"type" : "string",
"store" : true
},
"longitude" : {
"type" : "string",
"store" : true
},
...
Example 2: Get a sample of criminal offensescommitted in Astana:
/api/v4/mapping/astana_kalasynyn_kylmystyk_kuk1
* If there aremore than one version of dataset, then specify the desired version, for example:
/api/v4/mapping/astana_kalasynyn_kylmystyk_kuk1/v1
Response:
{
"astana_kalasynyn_kylmystyk_kuk1" : {
"mappings" : {
"v1" : {
"properties" : {
"city_code" : {
"type" : "string",
"store" : true
},
"crime_code" : {
"type" : "string",
"store" : true
},
"dat_sover" : {
"type" : "string",
"store" : true
},
"hard_code" : {
"type" : "string",
"store" : true
},
"home_number" : {
"type" : "string",
"store" : true
},
"latitude" : {
"type" : "string",
"store" : true
},
"longitude" : {
"type" : "string",
"store" : true
},
...
Example 3:To getthe first 5 records from the dataset of criminal offenses committedin Astana city, indicate the meaning of size parameter:
/api/v4/astana_kalasynyn_kylmystyk_kuk1/v1?source={"size": 5}
In case if there aremore than 1 version of dataset, you can replace the version with the desired one, for example:
/api/v4/astana_kalasynyn_kylmystyk_kuk1/v3?source={"size": 5}
Response:
[ {
"dat_sover" : "01.01.2016",
"street" : "ДОСТЫЌ",
"stat" : "ст.293 ч.2",
"time_period" : "1",
"organ" : "УВД районаЕсиль",
"crime_code" : "2930",
"hard_code" : "2",
"month" : "1",
"longitude" : "71.434872580000004",
"year" : "2016",
"city_code" : "г. Астана",
"ud" : "167115030000038",
"latitude" : "51.126707959999997",
"objectid" : "2316830",
"home_number" : "13",
"reg_code" : "РайонЕсил"
}, {
"dat_sover" : "01.01.2016",
"street" : "САУРАН",
"stat" : "ст.190 ч.1",
"time_period" : "3",
"organ" : "УВД районаЕсиль",
"crime_code" : "1900",
"hard_code" : "1",
"month" : "1",
"longitude" : "71.422323582999994",
"year" : "2016",
"city_code" : "г. Астана",
"ud" : "157115030024346",
"latitude" : "51.121251012999998",
"objectid" : "2139389",
"home_number" : "6/1",
"reg_code" : "РайонЕсил"
},
...
Example 4:To get 3 records from the criminal offensescommitted in Astana city while missing the first five, indicate the parameter from:
/api/v4/astana_kalasynyn_kylmystyk_kuk1/v1?source={"from":5, "size": 3}
Response:
[ {
"dat_sover" : "01.01.2016",
"street" : "МЈСКЕУ",
"stat" : "ст.188 ч.1",
"time_period" : "1",
"organ" : "СарыаркинскийРУВД",
"crime_code" : "1880",
"hard_code" : "2",
"month" : "1",
"longitude" : "71.397837250999999",
"year" : "2016",
"city_code" : "г. Астана",
"ud" : "167113030000156",
"latitude" : "51.180052580000002",
"objectid" : "860949",
"home_number" : "14/3",
"reg_code" : "РайонСарыарка"
}, {
"dat_sover" : "01.01.2016",
"street" : "КОНСТИТУЦИИ",
"stat" : "ст.191 ч.1",
"time_period" : "1",
"organ" : "СарыаркинскийРУВД",
"crime_code" : "1910",
"hard_code" : "2",
"month" : "1",
"longitude" : "71.393267264000002",
"year" : "2016",
"city_code" : "г. Астана",
"ud" : "167113030000082",
"latitude" : "51.195856544999998",
"objectid" : "1932847",
"home_number" : "19",
"reg_code" : "РайонСарыарка"
},
...
Example 5: Search by fields: get the list ofcriminal offensescommitted in Astana city in Imanov street, and also with the2nd severity of offense:
/api/v4/astana_kalasynyn_kylmystyk_kuk1/v1?source={
"size":100,
"query": {
"bool":{
"must":[
{"match":{"hard_code": "2"}},
{"match":{"street": "Иманова"}}
]
}
}
}
Search for objects is performed where the "hard_code" field contains "2"substring, and “street” field contains “Иманова”substring. The response contains all the objects for which both terms areperformed. Names of the fields, as well as also their types can be clarified in accordance with example 1.
Response:
[ {
"dat_sover" : "18.02.2016",
"street" : "ИМАНОВА",
"stat" : "ст.188 ч.1",
"time_period" : "1",
"organ" : "Алматинский РУВД",
"crime_code" : "1880",
"hard_code" : "2",
"month" : "2",
"longitude" : "71.444085013999995",
"year" : "2016",
"city_code" : "г. Астана",
"ud" : "167111030008206",
"latitude" : "51.164931746000001",
"objectid" : "1942307",
"home_number" : "21",
"reg_code" : "Район Алматы"
}, {
"dat_sover" : "22.05.2016",
"street" : "ИМАНОВА",
"stat" : "ст.120 ч.1",
"time_period" : "1",
"organ" : "Алматинский РУВД",
"crime_code" : "1200",
"hard_code" : "2",
"month" : "5",
"longitude" : "71.434266149999999",
"year" : "2016",
"city_code" : "г. Астана",
"ud" : "167111030026076",
"latitude" : "51.163761094000002",
"objectid" : "2431516",
"home_number" : "9",
"reg_code" : "Район Алматы"
},
...
Example 6: Obtain the healthcareorganizations located in Akmola region within a 10 km radius of coordinates (51.608524, 68.171934) in the geoposition field (this may be used in the event that the field type is indicated as “geoposition” in the dataset.
/api/v4/medorg/v1?source={
"size":100,
"query": {
"filtered": {
"query":{
"bool":{
"must":[
{"match":{ "address": "Акмолинская" }}
]
}
},
"filter": {
"geo_distance": {
"distance": "10km",
"geoposition": {
"lat": 51.608524,
"lon": 68.171934
}
}
}
}
}
}
Response:
[ {
"region" : "Акмолнская область",
"id" : 148,
"address" : "Акмолинская область, Атбасарский район, село Самарка",
"geoposition" : "51.602993, 68.032539",
"name" : "Самарский МП"
}, {
"region" : "Акмолнская область",
"id" : 125,
"address" : "Акмолинская область, Атбасарский район, село Сергеевка",
"geoposition" : "51.653683, 68.198503",
"name" : "Сергеевская ВА"
},
...
/api/v4/medorg/v1?source={
"size":100,
"query": {
"filtered": {
"query":{
"bool":{
"must":[
{"match":{ "region": "Южно-Казахстанскаяобласть" }}
]
}
},
"filter": {
"geo_distance": {
"distance": "1200m",
"geoposition": {
"lat": 42.359461,
"lon": 69.622625
}
}
}
}
},
"sort": [{
"_geo_distance": {
"geoposition": {
"lat": 42.359461,
"lon": 69.622625
},
"order": "asc",
"unit": "m"
}
}]
}
Response:
[ {
"region" : "Южно-Казахстанская область",
"id" : 3178,
"address" : "г.Шымкент, мкрНурсат, стр 125/1",
"geoposition" : "42.359461, 69.622625",
"name" : "ГККП "
}, {
"region" : "Южно-Казахстанская область",
"id" : 3230,
"address" : "г.Шымкент, мкрНурсат б /н",
"geoposition" : "42.358324, 69.627430",
"name" : "ГКП на ПХВ "
},
...
Example 8: Search as per fields: derive the list in descending order of remoteness from coordinates (42.358324, 69.627430) as per geoposition field(this may be used in the event that the field type is indicated as “geoposition” in the dataset):
/api/v4/medorg/v1?source={
"size":100,
"query": {
"bool":{
"must":[
{"match": {"region": "Южно"}},
{"match": {"address": "Шымкент"}}
]
}
},
"sort": [{
"_geo_distance": {
"geoposition": {
"lat": 42.358324,
"lon": 69.627430
},
"order": "asc",
"unit": "km"
}
}]
}
Response:
[ {
"region" : "Южно-Казахстанская область",
"id" : 3204,
"address" : "г. Шымкент, ул. ЖибекЖолы б/н",
"geoposition" : "42.330978, 69.626532 ",
"name" : "ГККП "
}, {
"region" : "Южно-Казахстанская область",
"id" : 3229,
"address" : "г. Шымкент ул. Толстого б/н",
"geoposition" : "42.320622, 69.620595",
"name" : "Шымкентская городская станция скорой медицинской помощи"
},
...
Example 9:FuzzySsearch:Fields parameter may accept names of several fields, as well as "all", if there is a need forsearchingacrossall fields.
Fuzziness field (edition distance) bydefault is equal to 2.
More details can be found in the official elasticsearchdocumentation
Query1:
This request performs fuzzy search of a word by all fields in the specified dataset
/api/v4/medorg/v1?source={
"size":2,
"query": {
"fuzzy_like_this" : {
"fields" : ["_all"],
"like_text" : "Астни"
}
}
}
Response 1:
[ {
"region" : "Астана",
"id" : 845,
"address" : "ул.Сарыарка",
"geoposition" : "51.076148, 71.424524",
"name" : "ГУ "
}, {
"region" : "Астана",
"id" : 873,
"address" : "микрорайон 3",
"geoposition" : "51.147495, 71.471863",
"name" : "ТОО « АкадемияортопедииАстана»"
} ]
Query2: Example of using the fuzziness parameter:
/api/v4/medorg/v1?source={
"size":3,
"query": {
"fuzzy_like_this" : {
"fields" : ["region"],
"like_text" : "Астани",
"fuzziness" : "1"
}
}
}
Response 2:
[ {
"region" : "Астана",
"id" : 820,
"address" : "ул. Т. Рыскулова,8",
"geoposition" : "51.083505, 71.413128",
"name" : "Центр семейного здоровья «Шипагер»"
}, {
"region" : "Астана",
"id" : 865,
"address" : "ул. Жибек жолы,76",
"geoposition" : "51.179823, 71.419469",
"name" : "ТОО «ФрезениусМедикалКейрКазахстан»"
}, {
"region" : "Астана",
"id" : 817,
"address" : "ул. Абылайхана,30",
"geoposition" : "51.128850, 71.461773",
"name" : "ЦПМСМ "
} ]
Example 10: Fuzzy search in combination with search by geo position
The objects are searched for that contain words with editiorialinterval (fuzziness) 2 from "Астани" word across all fields. Response is provided as a list of objects sorted as per remoteness from coordinates (51.168803, 71.444856) in the geoposition field
/api/v4/medorg/v1?source={
"size":100,
"query": {
"fuzzy_like_this" : {
"fields" : ["_all"],
"like_text" : "Астани"
}
},
"sort": [{
"_geo_distance": {
"geoposition": {
"lat": 51.168803,
"lon": 71.444856
},
"order": "asc",
"unit": "km"
}
}]
}
Response:
[ {
"region" : "Астана",
"id" : 836,
"address" : "ул. Кенесары 82",
"geoposition" : "51.167188, 71.441343",
"name" : "ТОО "
}, {
"region" : "Астана",
"id" : 815,
"address" : "ул. Сембинова,4/1",
"geoposition" : "51.166105, 71.448100",
"name" : "ГКП на ПХВ «Городская поликлиника №8»"
},
...
Detailed Api
Detailed Api description
These inquiries allow receiving more detailed information on inquired datasets
/api/detailed/dataset?source={Query in Json Object}
/api/detailed/dataset/version?source={Query in Json Object}
This inquiry carries out search in the dataset. At that, the source parameter is transferred, which describes how exactly the search and filtration shall be made.
vversion is not an obligatory attribute
The server response comes back in JSON format. It contains a selection of data or an error message.
Examples of inquiries are given below.
Example 1:
To receive a detailed selection from the pharmacies directory:
The inquiry is as follows:
/api/detailed/pharmacy/v1
Response:
{
"totalCount" : 56, //Total number of objects
"data" : [ { //Array of objects
"_index" : "pharmacy", //Index of dataset
"_type" : "v1", //Version of dataset
"_id" : "28", //Unique identifier
"id" : 28,
"Name" : "Гиппократ № 30",
"Region" : 17108,
"geoposition" : "51.169886,71.436908",
"Address" : "г. Астана, ул. Абая д.59"
},
...
Example 2:
It is also possible to make aggregations by fields of datasets. Details can be found in official documentation elasticsearch.
To calculate the average coefficient of quality of education for 2012-2013 academic year:
The inquiry is as follows:
/api/detailed/sch_rating/data?source={
"aggs" : {
"average_quality" : { "avg" : { "field" : "KnowledgeQuality20122013" }
}
}
}
Response:
{
"totalCount": 70,
"data": [
{
"UNTresults": "89.05",
"СonformityLevel": "1 из 1",
"KnowledgeQuality20122013": "62.3",
"_index": "sch_rating",
"FullName": "№17 школа-гимназия",
"_type": "data",
"ID": "16",
"_id": "16"
},
...
"aggregations": {
"average_quality": {
"value": 55.2250723907913 //Cредний коэффициент качества образования
}
}
}
Meta information
These inquiries allow users to extract meta information on datasets being of interest to them.
/meta/dataset/version
This inquiry extracts meta data on a dataset and version.
The server response comes back in JSON format. It contains an object or an error message.
An example of inquiry is given below.
Example:
To receive meta information on the dataset of Pharmacies:
The inquiry is as follows:
/meta/pharmacy/v1
Response:
{
"apiUri" : "pharmacy"
"nameRu" : "Аптеки",
"nameEn" : "Pharmacy",
"nameKk" : "Дәріханалар",
"descriptionRu" : "Данный набор содержит наименования аптек, коды ...",
"descriptionEn" : "This set contains names of pharmacies, codes of ...",
"descriptionKk" : "Осы жиынтық дәріханалар, өңірлер кодтары мен ...",
"responsible" : {
"phone" : "+7 123 456 78 90",
"phone" : "test@test.kz",
"fullnameKk" : "Дәріханалар",
"fullnameEn" : "Pharmacy",
"fullnameRu" : "Аптеки"
},
"createdDate" : "2015-01-05T13:53:19.702Z",
"modifiedDate" : "2015-01-05T13:53:19.702Z",
"fields" : {
"id" : {
"labelKk" : "Id",
"labelEn" : "Id",
"type" : "Int",
"labelRu" : "Id"
},
"Name" : {
"labelKk" : "Name",
"labelEn" : "Name",
"type" : "String",
"labelRu" : "Name"
},
"Region" : {
"labelKk" : "Region",
"labelEn" : "Region",
"type" : "Int",
"labelRu" : "Region"
},
"geoposition" : {
"labelKk" : "Geoposition",
"labelEn" : "Geoposition",
"type" : "Geoposition",
"labelRu" : "Geoposition"
},
"Address" : {
"labelKk" : "Address",
"labelEn" : "Address",
"type" : "String",
"labelRu" : "Address"
}
}
}
