Европейский портал
информации здравоохранения

Материалы и первые шаги
Портал Страны Данные
Данные
Путеводитель по показателям
Материалы и первые шаги Посетить основной сайт ВОЗ?
Базы данных
База данных "Здоровье для всех" (HFA-DB) Информационные системы здравоохранения и управление данными Искусственный Интеллект для Здравоохранения в Европейском регионе ВОЗ Ассистивные технологии Европейская программа работы Цифровое Здравоохранения Европейская база данных о смертности (MDB) Реабилитация Оздоровительная физическая активность Европейская база данных кадровых и технических ресурсов здравоохранения (HlthRes-DB) Европейская информационная система по окружающей среде и здоровью (ENHIS) Финансовой защиты в европейском регионе
Мониторинг
Здоровье детей и подростков Политика вакцинации против сезонного гриппа и охват вакцинацией
Отчетность
Поведение детей школьного возраста в отношении здоровья (HBSC) Питание матери, физическая активность и увеличение массы тела во время беременности Устойчивость к противомикробным препаратам Глобальный обзор политики в области питания Состояние политик в отношении здоровья детей и подростков в Европе
Архив
Показатели для Здоровье-2020 Обследование в области электронного здравоохранения, 2015 г. Единый механизм мониторинга (ЕММ)
Данные Базы данных Мониторинг Отчетность Архив
Материалы и первые шаги Посетить основной сайт ВОЗ?
API

Спецификации API

Содержание:

Спецификации API

При помощи Data Warehouse API разработчики программного обеспечения могут получить программный доступ к содержимому баз данных Европейского регионального бюро ВОЗ. Этот API позволяет найти недавно добавленные наборы данных, производить поиск по данным, скачивать данные для анализа или искать показатели и наборы данных, объединенные общей темой.

Общая структура модели данных:

1. Показатель (measure) – это ряд данных, который служит наполнением конкретного индикатора или другой измеримой категории. Иными словами, показатель вмещает в себя совокупность значений данного индикатора для всех стран, для которых он определен, или совокупность ответов этих стран на отдельный вопрос анкеты. У показателя есть метаданные и свойства (единицы измерения, тип показателя и т. д.).

2. Каждый показатель сопровождается пояснениями, в которых дается его определение, а также примечаниями по странам, в которых приводится информация о специфике данных по той или иной стране.

3. Ряд показателей может быть объединен в набор данных. У каждого набора данных также есть метаданные и свойства (владелец данных и т. д.).

4. Показатели по смежным темам также могут быть объединены в тематические классификации. Классификации позволяют запрашивать показатели, относящиеся к разным наборам данных, но связанные тематически.

Настоящая спецификация относится к Data Warehouse API версии 3.8.4. В ней есть следующие разделы:

 

  • Data Warehouse (DW) – центральное хранилище данных здравоохранения, полученных из разных источников.
  • API  (программный интерфейс) – система, определяющая порядок программного взаимодействия с данными, которые хранятся в Data Warehouse. Для передачи запроса используется протокол HTTP, для передачи объектов в ответ на запрос – формат JSON (CSV).
  • JSON (JavaScript Object Notation) – удобный для восприятия человеком открытый формат обмена данными, в котором данные представляются в виде пар «ключ – значение».
  • CSV (comma-separated values) – простой текстовый формат для представления табличных данных, в котором столбцы и ряды разделяются запятыми.
  • Метаданные определяют структуру данных, хранимых в Data Warehouse, включая такие элементы, как показатели, свойства, коды свойств показателей, коды свойств фактов и пояснения. Можно скачать все метаданные одним файлом Excel (/api/v5/export_metadata) или запрашивать выгрузку метаданных в формате Excel по отдельным показателям.
  • Показатель – набор фактов с уникальным кодом и названием на двух языках, который определяет содержимое показателя. Чаще всего показатель приравнивается к индикатору.
  • Факт – набор кодов свойств, описывающих значение. Отдельные факты объединяются в показатель.
  • Свойство описывает показатель или факт определенным образом.
    • Свойства факта описывают его измерения (например, YEAR – год, SEX – пол, VACCINATIONSTATUS – статус вакцинации).
    • Свойства показателя (EXTERNID, DATA_SOURCE, UNIT_TYPE) содержат информацию о нем. DATA_SOURCE – свойство, определяющее источник данных. EXTERNID – идентификатор показателя во внешнем источнике данных (если таковой использован). UNIT_TYPE – единицы измерения.
    • COUNTRY_GROUP – свойство, обозначающее группу стран, по которой имеются усредненные значения. Состав групп стран определяется связями между странами и группами стран. Пример: в группу WHO_EURO входят 53 страны Европейского региона ВОЗ, а в группу CARINFONET – страны-члены Информационной сети по вопросам здравоохранения республик Центральной Азии.
    • COUNTRY – свойство, обозначающее, что данные относятся к стране, в порядке исключения – к субнациональной единице.
  • Набор данных – это совокупность показателей, образующая связное, поддающееся анализу множество. Чаще всего набор данных представляет собой подборку показателей из базы данных, результат мероприятий по сбору данных, данные, полученные в рамках системы мониторинга или приведенные в аналитической публикации. Один показатель может принадлежать к нескольким наборам данных, хранящимся в Data Warehouse.
  • Пояснение ­– текстовое поле, содержащее описание набора данных (в случае пояснения к набору данных) или показателя (в случае пояснения к показателю, в котором приводится его определение). Кроме того, в пояснениях к страновым показателям можно найти информацию о специфике данных по конкретным странам. Эта информация помогает понять особенности источника данных, набора данных или показателя.
  • Классификация в контексте Data Warehouse – это своеобразное «оглавление» для набора показателей. Все показатели, принадлежащие к определенной категории в классификации, имеют отношение к соответствующей теме. Классификационная иерархия может охватывать конкретный набор данных и описывать отношения между отдельными показателями. Мастер-классификация объединяет все показатели в единую унифицированную структуру.

Стандарт написания кода в Data Warehouse построен на мнемонических принципах, для того чтобы облегчить восприятие и сделать возможным просмотр наборов данных человеком (за основу взят английский язык).

URL для работы с интерфейсом формируется следующим образом:

http://HOST[:PORT]/api/v5/CONTROLLER[/CODE][?QUERY_PARAMETERS]

При отсутствии каких-либо дополнительных опций структура URL выглядит так:

http://HOST/api/v5/CONTROLLER

По такому запросу будет выдан перечень имеющихся вхождений по указанному контроллеру.

Чтобы получить подробную информацию о вхождении, нужно указать его код. Указав нужные параметры запроса, можно выбрать язык ответа, применить к данным фильтр (в списке вхождений или данных внутри вхождения) или выбрать части вхождения, которые необходимо получить.

  • HOST: домен веб-сервиса. Для доступа к API нужно указать домен http://dw.euro.who.int.
  • PORT: номер порта веб-сервиса. Можно не указывать или указать порт HTTP по умолчанию (80).
  • CONTROLLER: код контроллера для получения данных. Возможные контроллеры:
    • countries
    • country_groups
    • data_sets
    • measures
    • version
    • export_metadata
    • export_data_set
    • classifications
    • categories

      Каждый контроллер выдает разные виды данных.
  • CODE: код нужного вхождения.
  • QUERY_PARAMETERS: опциональные параметры запроса, которые могут быть применимы только к некоторым запросам. Возможные параметры:
    • lang – язык ответа. EN – английский, RU – русский. По умолчанию выдается ответ на английском.
    • filter – может использоваться для применения фильтра к показателям или к фактам внутри показателя. Значение фильтра – список токенов, разделенных точками с запятой, в формате ATTRIBUTE:CODES_LIST.
      CODES_LIST – это:
      • список разделенных запятыми кодов,
      • " * " — любое установленное значение,
      • " $blank " — неустановленное значение,
      • диапазоны вида 1999-2004 (если значение поля ATTRIBUTE является числовым),
      • " ~[year] " или " [year]~ " — фильтр по ближайшему доступному году, где знак " ~ "означает направление поиска данных, например ~2001 — при отсутствии данных за 2001 г. выводятся данные за ближайший предшествующий год.

      К кодам в рамках одного свойства применяется логическое ИЛИ. К разным свойствам применяется логическое И.

      Атрибут COUNTRY поддерживает коды COUNTRY_GRP, так как значения CODES_LIST означают страны, относящиеся к конкретным группам стран.
    • output – используется при контроллерах measures и categories, чтобы выбрать те части объекта, которые необходимо получить. Возможные значения для measures: data, metadata, attributes, notes и classifications; для categories: measures и subtree. Можно задать либо одно из этих значений, либо список значений, разделенный запятыми.
    • updated_since – позволяет получить информацию о показателях и источниках данных, которые были изменены после той или иной даты.
    • dataState – позволяет скачивать коды и метки показателей и классификаций, которые не опубликованы в Data Warehouse.
    • format – задает формат экспортируемых файлов. Используется только при экспорте и может иметь значение xlsx либо csv.

 

Ответ на запрос Data Warehouse API направляет в формате объекта JSON. JSON – это формат обмена данными, который пригоден для чтения как компьютером, так и человеком. Структура объекта будет различаться в зависимости от контроллера.

Если запросить список стран, находящихся в составе Европейского региона ВОЗ, при помощи URL /api/v5/country_groups/WHO_EURO, будет получен следующий ответ:

{  
    "code":"WHO_EURO",
    "short_name":"WHO European Region",
    "full_name":"WHO European Region",
    "countries":[  
       {  
          "code":"ALB",
          "iso2":"AL",
          "iso3":"ALB",
          "who_code":"ALB",
          "short_name":"Albania",
          "full_name":"Albania"
       },
       {  
          "code":"AND",
          "iso2":"AD",
          "iso3":"AND",
          "who_code":"AND",
          "short_name":"Andorra",
          "full_name":"Andorra"
       },
       (...)
   ]
 }

Первые три ключа – это идентификационный код (code), присвоенный Европейскому региону ВОЗ, короткое название (short_name) и полное название (full_name). В этом примере короткое название и полное одинаковы, но они могут различаться. Короткое название может использоваться при отображении списков. Указанные свойства всегда выдаются по запросу /api/v5/country_groups/WHO_EURO, но в целом состав ключей зависит от конкретного запроса.

Далее идет блок стран (countries), в котором содержится информация о входящих в группу странах. У каждой страны несколько свойств, в данном случае code, iso2, iso3, who_code, short_name и full_name. Эти свойства всегда выдаются при запросе /api/v5/country_groups/WHO_EURO.

Ниже приводятся примеры возможных запросов в Data Warehouse.

 

Для того чтобы узнать текущую версию API, используйте следующий URL: /api/v5/version.

Новые версии выпускаются при существенном изменении формата ответа или обновлении функционала API. Старые версии через некоторое время выводятся из эксплуатации. Рекомендуется следить за текущей версией API и по возможности использовать последнюю версию.

 

Можно получить список вхождений по отдельным контроллерам. Это полезно, когда нужно знать, какие объекты есть в наличии, например получить перечень наборов данных, имеющихся в Data Warehouse, или запросить список стран, их названий и кодов. Язык по умолчанию – английский, при необходимости можно получить информацию на русском.

Для того чтобы получить список вхождений, используйте один из следующих URL:

 

Для того чтобы получить подробную информацию о вхождении, укажите его код. Информацию можно получить разными способами, что позволяет не разрабатывать функционал специально для приложения, а использовать возможности API. API предоставляет информацию всегда в одном и том же формате.

Указав код вхождения в URL, вы получите подробную информацию об этом вхождении. Например, подробная информация по стране будет включать список групп стран, к которой она принадлежит; подробная информация по показателю будет содержать список метаданных, свойств, пояснений и классификаций, относящихся к этому показателю.

 

Для того чтобы выбрать язык ответа, используйте параметр запроса lang. Он может принимать значения EN (английский) или RU (русский). Благодаря наличию данных на двух языках можно разрабатывать двуязычные приложения. По умолчанию (если параметр не указан) ответ выдается на английском.

 

Для того чтобы выбрать, какие части объекта, содержащего данные по показателю, вы хотите получить, нужно задать параметру output одно из следующих значений: attributes, metadata, data, notes, classifications, data_sets или dimensions – либо указать их список, разделенный запятой. Таким образом можно запросить только ту информацию, которая нужна в данный момент, например для создания таблицы или графика с использованием данных того или иного показателя.

 

Фильтр можно применять только к двум видам вхождений: показатели и факты. Отфильтровав по источнику данных (DATA_SOURCE), вы получите список показателей, имеющихся в этом источнике данных. Можно также фильтровать по году или по временному диапазону, чтобы получить данные за интересующий период.

Показатели фильтруются по свойствам, содержащим метаданные:

  • /api/v5/measures?filter=DATA_SOURCE:HFA – выдает показатели, у которых в качестве источника данных указана база данных HFA.
  • /api/v5/measures?filter=UNIT_TYPE:NUM_BEDS,NUM_DAYS – выдает показатели, у которых в качестве единицы измерения указано либо количество коек (NUM_BEDS), либо количество суток (NUM_DAYS).
  • /api/v5/measures?filter=DATA_SOURCE:HFA,ENHIS;UNIT_TYPE:KM2 – выдает показатели, у которых источник данных – либо H2020, либо ENHIS, а единица измерения – квадратные километры.

Факты фильтруются следующим образом:

Показатели и наборы данных также можно фильтровать по дате последнего обновления:

В ответ на запрос определенного набора данных или показателя с параметром запроса updated_since выдается значение true, если набор данных или показатель был обновлен после определенной даты, в противном случае выдается значение false:

  • /api/v5/data_sets/HBSC?updated_since=2016-01-05 – выдает true, потому что набор данных HBSC обновлялся после 5 января 2016 г.
  •  – выдает false, потому что набор данных H2020 не обновлялся после 09:30 19 июля 2017 г.
  • /api/v5/measures/H2020_10?updated_since=2017-01-01 – выдает false, потому что показатель H2020_10 не обновлялся после 1 января 2017 г.

 

Факты в составе показателя можно фильтровать по стране. Это полезно, когда нужно ограничить круг запрашиваемых данных и работать только с конкретными странами. Есть также два способа работать с группами стран: задав фильтр COUNTRY со значением $blank или фильтр COUNTRY_GRP со значением *. Примеры:

 

Можно экспортировать данные в формате CSV или Excel, чтобы работать с ними в приложениях, не подключенных к API, например в Excel. При экспорте показателей по умолчанию используется формат Excel.

Ответ на каждый запрос на экспортирование (для показателя или набора данных) поступает в формате JSON.

{
    "status": "InQueue",
    "time_elapsed_seconds": 0,
    "check_status_url":"/api/v5/export/status/c2df1c001eb64309b12f97a920bc3ecc"
}

Первое свойство – код состояния процесса экспортирования. Перечень возможных состояний:

  • «InQueue» – файл в очереди на обработку;
  • «Processing» – запущен процесс создания файла;
  • «Generated» – файл создан и готов для скачивания;
  • «Failed» – не удалось создать файл.

Второе свойство – «time_elapsed_seconds» – отражает время, прошедшее в секундах с момента запроса файла. Свойство присутствует лишь во время состояний «InQueue» и «Processing». Свойство «check_status_url» содержит URL для проверки хода процесса экспортирования во время состояний «InQueue» и «Processing».

Когда создание файла завершается и он становится доступным для скачивания, отображается следующий ответ:

{
    "status": "Generated",
    "generated_time": "2018-01-21T13:45:21.2249016",
    "file_size_kb": 59,
    "download_url":"/api/v5/export/download/6522933299f54d20b58dd013b506dd2"
}

Свойство «generated_time» представляет собой дату и время создания файла, представленные в формате ISO. Свойство «file_size_kb» показывает размер созданного файла в килобайтах. Свойство «download_url» содержит URL для прямого доступа к файлу.

Ниже представлены примеры URL для экспортирования с применением различных фильтров:

Экспорт одного показателя:

Можно экспортировать несколько показателей в одном файле:

Возможно также экспортировать набор данных или некое подмножество содержащихся в нем показателей. Если нужно работать со всеми показателями в режиме оффлайн, можно экспортировать набор данных целиком:

  • /api/v5/export_data_set/H2020 – экспортировать zip-файл который содержит метаданные и данные по показателям, которые принадлежат к набору данных H2020.
  • /api/v5/export_data_set/H2020?measures=H2020_1,H2020_2,H2020_3 – экспортировать zip-файл который содержит метаданные и данные по показателям H2020_1, H2020_2 и H2020_3 из набора данных H2020.

Если нужна только какая-то конкретная часть показателя или набора данных, можно фильтровать экспортированные факты показателя по свойствам. Например, в базе данных HFAMDB имеются факты на национальном и субнациональном уровне, и можно выставить фильтр так, чтобы получить только те данные, которые необходимы. Таким образом, если вам не нужны факты по всем показателям, содержащимся в наборе данных, при экспорте следует использовать фильтр:

  • /api/v5/export/HFAMDB_1?filter=SUBNATIONAL_MDB:$blank – экспортировать файл Excel с фактами показателя HFAMDB_1, у которых не определено свойство SUBNATIONAL_MDB.
  • /api/v5/export/HFAMDB_1?filter=SUBNATIONAL_MDB:*&format=csv&lang=ru – экспортировать файл CSV на русском с фактами показателя HFAMDB_1, у которых  определено свойство SUBNATIONAL_MDB.
  • /api/v5/export_data_set/H2020?filter=COUNTRY_GRP:NORDIC – экспортировать zip-файл который содержит метаданные и данные по показателям, принадлежащими к набору данных H2020. В файл включаются только факты, относящиеся к группе стран NORDIC (страны Северной Европы).
  • /api/v5/export_data_set/H2020?measures=H2020_1,H2020_2,H2020_3&filter=COUNTRY:UKR – экспортировать zip-файл который содержит метаданные и данные по показателям H2020_1, H2020_2 и H2020_3 из набора данных H2020. В файл включаются только факты, относящиеся к Украине.

 

Можно экспортировать часть метаданных или все метаданные, содержащиеся в Data Warehouse. Это делается в тех случаях, когда необходимо работать с метаданными и данными в режиме оффлайн, не имея непрерывного доступа к API. Метаданные экспортируются только в формате Excel:

 

Запрос classifications позволяет получить список имеющихся классификаций показателей. Классификации – это средство организованного хранения показателей, поэтому их можно просматривать иерархически.

При помощи контроллера categories можно получить подробную информацию о классификациях, например о подкатегориях или показателях, которые содержатся в той или иной подкатегории:

  • /api/v5/categories/D – выдает всё древо классификации D с категориями, подкатегориями, подкатегориями следующего уровня (если они существуют) и показателями, которые к ним отнесены.
  • /api/v5/categories/D03_00 – выдает показатели, которые отнесены к категории D03_00 и ее подкатегориям (если таковые есть).
  • /api/v5/categories/D03_00?output=measures – выдает показатели, отнесенные к категории D03_00, без учета ее подкатегорий.
  • /api/v5/categories/D03_00?output=subtree – выдает список подкатегорий, имеющихся внутри категории D03_00, без отнесенных к ним показателей.
  • /api/v5/categories – выдает всё древо классификации для всех классификаций с перечислением показателей, отнесенных к каждой категории.
  • /api/v5/categories?output=subtree – выдает всё древо классификации для всех классификаций без учета отнесенных к ним показателей.
  • /api/v5/measures/HFA_1?output=classifications – каждый показатель имеет свойство classifications, в котором содержится список категорий, к которым отнесен этот показатель в соответствии с каждой классификацией. При помощи этого запроса можно получить список категорий, к которым отнесен показатель, с тем чтобы запросить тематически связанные показатели.

 

Можно запросить список наборов данных, имеющихся в Data Warehouse, или список показателей, представленных в том или ином наборе. Такие запросы позволяют получить общую информацию о том, какие данные имеются в Data Warehouse.

  • /api/v5/data_sets – выдает список всех имеющихся наборов данных.
  • /api/v5/data_sets/H2020 – выдает список всех показателей, содержащихся в указанном наборе данных.

Для того чтобы получить данные по показателю в контексте определенного набора данных:

  • /api/v5/data_sets/H2020/H2020_1 – выдает данные по показателю H2020_1 в контексте набора данных H2020 – со списком стран, определенным для этого набора, пояснениями к набору и т. д.