Описание API

Описание API версии 4

Обмен данными между клиентской частью (Android/iOS приложение) и сервером data.egov.kz осуществляется через протокол HTTPS. Поиск по данным реализован с использованием технологии elasticsearch. При запросе параметры передаются по протоколу HTTPS методом GET в следующем формате:

/api/v4/dataset?source={Query in Json Object}
/api/v4/dataset/version?source={Query in Json Object}
Данный запрос осуществляет поиск по набору данных dataset, при этом передается параметр source, который описывает как именно должен производиться поиск и фильтрация.

/api/v4/mapping/dataset
/api/v4/mapping/dataset/version
Данный запрос описывает поля записей, используемых в наборе данных dataset

Ответ сервера возвращается в формате JSON, он содержит выборку данных или сообщение об ошибке.

Ниже приведены примеры запросов.

Пример 1:

Вывести описание полей с их типами и структурой, а также версии набора.

Для получения списка полей и их типов выполните запрос указанный ниже.

Запрос выглядит следующим образом:

/api/v4/mapping/astana_kalasynyn_kylmystyk_kuk1

Ответ:

{
  "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
          },
...

Пример 2:

Получить выборку из совершенных уголовных преступлений по Астане:

/api/v4/mapping/astana_kalasynyn_kylmystyk_kuk1

* В случае если у набора имеется более 1 версии, нужно указать необходимую версию, например:

/api/v4/mapping/astana_kalasynyn_kylmystyk_kuk1/v1

Ответ:

{
  "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
          },
                 ...

Пример 3:

Чтобы получить первые 5 записей из набора данных по совершенным уголовным преступлениям г.Астана укажите значение параметра size:


/api/v4/astana_kalasynyn_kylmystyk_kuk1/v1?source={"size": 5}

 * В случае если у набора имеется более 1 версии, Вы можете заменить версию на необходимую Вам, например:

/api/v4/astana_kalasynyn_kylmystyk_kuk1/v3?source={"size": 5}

Ответ:

[ {
  "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" : "РайонЕсил"
},
            ...          

Пример 4:

Чтобы получить 3 совершенных уголовных преступлениях пог.Астана, при этом пропустив первые 5, укажите параметр from:

/api/v4/astana_kalasynyn_kylmystyk_kuk1/v1?source={"from":5, "size": 3}

Ответ:

[ {
  "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" : "Район Сарыарка"
},
         ...

Пример 5: Поиск по полям: вывести почтовые отделения Астаны, работающие без перерыва по улице Сыганак.

Поиск по полям: вывести перечень совершенных уголовных преступлений по г. Астана по улице Иманова, а также 2ой тяжестью преступления.

/api/v4/astana_kalasynyn_kylmystyk_kuk1/v1?source={
            "size":100,
            "query": {
              "bool":{
                "must":[
                  {"match":{"hard_code": "2"}},
                  {"match":{"street": "Иманова"}}
                ]
              }
            }
          }

Производится поиск объектов, где поле "hard_code" содержит подстроку "2" и поле "street" содержит подстроку "Иманова". Ответ содержит все объекты для которых выполняются оба условия. Наименование полей, а также их типы можно выяснить следуя примеру 1.

Ответ:

[ {
  "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" : "Район Алматы"
},     
...

Пример 6:

Получить медицинские организации РК, которые находятся в Акмолинской области, в радиусе 10 км от координат (51.608524, 68.171934) в поле geoposition (может быть использовано в том случае, если тип поля в наборе помечен как «geoposition»):

/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
                    }
                  }
                }
              }
            }
          }

Ответ:

[ {
  "region" : "Акмолнская область",
  "id" : 148,
  "address" : "Акмолинская область, Атбасарский район, село Самарка",
  "geoposition" : "51.602993, 68.032539",
  "name" : "Самарский МП"
}, {
  "region" : "Акмолнская область",
  "id" : 125,
  "address" : "Акмолинская область, Атбасарский район, село Сергеевка",
  "geoposition" : "51.653683, 68.198503",
  "name" : "Сергеевская ВА"
},
            ...

Пример 7:

Вывести все медицинские организации РК, находящиеся в Южно-Казахстанской области, в радиусе 1200 м от координат (42.359461, 69.622625) в поле geoposition и отсортированные в порядке удаленности от этих координат (может быть использовано в том случае, если тип поля в наборе помечен как «geoposition»):

/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"
                }
            }]
          }

Ответ:

[ {
  "region" : "Южно-Казахстанская область",
  "id" : 3178,
  "address" : "г.Шымкент, мкрНурсат, стр 125/1",
  "geoposition" : "42.359461,  69.622625",
  "name" : "ГККП "
}, {
  "region" : "Южно-Казахстанская область",
  "id" : 3230,
  "address" : "г.Шымкент, мкрНурсат б /н",
  "geoposition" : "42.358324,  69.627430",
  "name" : "ГКП на ПХВ "
},
         ...

Пример 8:

Поиск по полям: вывести список в порядке удаленности от координат (42.358324,  69.627430) по полю geoposition (может быть использовано в том случае, если тип поля в наборе помечен как «geoposition»):

/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"
              }
            }]
        }  

Ответ:

[ {
  "region" : "Южно-Казахстанская область",
  "id" : 3204,
  "address" : "г. Шымкент, ул. ЖибекЖолы б/н",
  "geoposition" : "42.330978, 69.626532 ",
  "name" : "ГККП "
}, {
  "region" : "Южно-Казахстанская область",
  "id" : 3229,
  "address" : "г. Шымкент ул. Толстого б/н",
  "geoposition" : "42.320622,  69.620595",
  "name" : "Шымкентская городская станция скорой медицинской помощи"
},
         ...

Пример 9: Нечеткий поиск (FuzzySearch).
Параметр fields может принимать наименование нескольких полей, а также "_all", если нужно искать по всем полям.
Параметр fuzziness (редакционное расстояние) по умолчанию равен 2
Более подробную информацию по нечеткому поиску можно найти в официальной документации elasticsearch


Запрос 1:
Данный запрос производит нечеткий поиск слова по всем полям в заданном наборе данных.

/api/v4/medorg/v1?source={
            "size":2,
            "query": {
              "fuzzy_like_this" : {
                "fields" : ["_all"],
                "like_text" : "Астни"
              }
            }
          }

Ответ 1:

[ {
  "region" : "Астана",
  "id" : 845,
  "address" : "ул.Сарыарка",
  "geoposition" : "51.076148, 71.424524",
  "name" : "ГУ "
}, {
  "region" : "Астана",
  "id" : 873,
  "address" : "микрорайон 3",
  "geoposition" : "51.147495, 71.471863",
  "name" : "ТОО « АкадемияортопедииАстана»"
} ]

Запрос 2: Пример использования параметра fuzziness:

/api/v4/medorg/v1?source={
            "size":3,
            "query": {
              "fuzzy_like_this" : {
                "fields" : ["region"],
                "like_text" : "Астани",
                "fuzziness" : "1"
              }
            }
          }

Ответ 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" : "ЦПМСМ "
} ]

Пример 10: Нечеткий поиск (FuzzySearch) в комбинации с поиском по геолокации.

Производится поиск объектов, содержащиx слова с редакционным расстоянием (fuzziness) 2  от слова "Астани"  по всем полям. Ответ предоставляется в виде списка объектов отсортированного по удаленности от координат (51.168803, 71.444856) в поле geoposition

/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"
              }
           }]
          }

Ответ:

[ {
  "region" : "Астана",
  "id" : 836,
  "address" : "ул. Кенесары 82",
  "geoposition" : "51.167188, 71.441343",
  "name" : "ТОО "
}, {
  "region" : "Астана",
  "id" : 815,
  "address" : "ул. Сембинова,4/1",
  "geoposition" : "51.166105, 71.448100",
  "name" : "ГКП на ПХВ «Городская поликлиника №8»"
},

           ...