Платформа открытых данных
Минкультуры России
Программный интерфейс (API)

Быстрый старт

1. Получение списка наборов данных

http://opendata.mkrf.ru/v1

В возвращаемом результате поле entityName содержит машинное имя набора данных, например subordinates для набора данных “Подведомственные организации Министерства культуры Российской Федерации”, на основании которого строятся остальные URL запросов к данным.

2. Получение документов из последней версии
http://opendata.mkrf.ru/v1/subordinates/$?l=10

Ответ содержит формализованные данные запроса и массив с документами. Полезная нагрузка каждого документа документа находится в поле data. Чтобы интерпретировать полезную нагрузку, достаточно запросить схему, соответствующую набору данных.

3. Получение JSON схему данных, и метаинформацию схемы

http://opendata.mkrf.ru/v1/subordinates/$/$schema

В ответе сервера поле jsonSchema содержит документ схемы согласно стандарту, причем схема является дополненной описательной информацией и расширенной информацией о типах.  Все представление данных в публичной части портала ОД строится на основании именно этих данных. Остальные поля содержат метаинформацию о схеме.

4. Получение данных по  искомой фразе

http://opendata.mkrf.ru/v1/subordinates/$?f={"data.name":"Третьяковская"}

Выполняется полнотекстовый морфологический поиск по документам версии набора данных. Поиск может быть многословный, например поиск по набору “Реестра прокатных удостоверений фильмов” http://opendata.mkrf.ru/v1/register_movies/$?f={"data.general.filmname":"полиция"}

5. Получение отдельных документов по главному идентификатору принятому в исходной системе, в данном примере используются ИНН

http://opendata.mkrf.ru/v1/subordinates/$/7710162150 - получение одного документа

http://opendata.mkrf.ru/v1/subordinates/$/[7710162150,7710130046,7704011869] - получение списка документов

6. Получение связанных документов

http://opendata.mkrf.ru/v1/subordinates/$?f={"data.name":"Третьяковская"}&links=

Найденные, в соответствии с фильтром, документы будет дополнены ссылками  по которым можно получить связанные документы из других наборов данных, например с целью получить другие характеристики этого же объекта. Так среди возвращаемых ссылок будет http://opendata.mkrf.ru/v1/schema/@57f67f157476ad0320dc9765/$?f=%7B%22data.general.organization.inn%22%3A%227706032800%22%7D
, которая вернет все документы из набора “
Музеи. Сведения об объектах социальной сферы”, имеющие такой же ИНН, как и у исходного документа из набора “Подведомственные организации Министерства культуры Российской Федерации”.

Общие правила и подходы

Идентификация документов в системе

Система для всех документов поддерживает  вида идентификаторов:

  1. Идентификаторы, которые поступили из сторонних систем (nativeId),  уникальные человеко-понятные имена наборов и схем, номера версий. Тип таких идентификаторов - строка. Все идентификаторы в запросах по умолчанию трактуются именно таким образом.
  2. Внутренние синтетические идентификаторы. Уникальные, в пределах системы, идентификаторы документов. Представляет собой число, задаваемое в  шестнадцатеричной кодировке. Для того, чтобы в запросе указать такой идентификатор, нужно перед ним поставить символ @. В параметрах запроса, где нет разночтения какой именно идентификатор имеется ввиду (например фильтрация по полю _id), префикс @ ставить не нужно.

В ряде случаев (обозначено в описании метода API) может быть использована маска идентификатора:

  1. $ обозначает “последнюю версию из имеющихся”
  2. @ обозначает “все версии”

Формат запросов

Все запросы могут быть построены по одному из 2х шаблонов:

GET /v1/<имя набора данных или имя метаданных>
/<версия набора данных или имя метаданных>
/<идентификатор документа или имя метаданных>?параметры

GET /v1/schema/<схема набора данных>
/<версия набора данных или имя метаданных>
/<идентификатор документа или метаданных>?параметры

, где все части пути после v1 являются необязательными. Части несут следующую смысловую нагрузку:

имя набора данных - идентификатор c префиксом @ или уникальное имя набора данных (entityName), зарегистрированного в системе

схема набора данных - идентификатор  схемы данных c префиксом @ или уникальное имя схемы набора

версия набора данных - одно из следующих выражений, позволяющее вычислить версию НД:

идентификатор документа или метаданных - идентификатор документа в исходной системе, идентификатор документа в системе открытых данных (c префиксом @) либо словарное значение - название метаданных схемы набора данных. На данный момент поддерживаются следующие значения идентификаторов метаданных:

$schema - метаданные схемы, включая JSON schema

$version - метаданные версии НД

$fields - плоский список полей схемы НД

$indexes - плоский список индексируемых полей схемы НД

$table - плоский список полей схемы НД, входящих в “человеко-ориентированное” представление

$links - список связей НД с другими наборами данных. Поддерживается параметр ?p= задающий заполнение данных схемы. Возможны такие значения:

destination  - только зависимые схемы

origin  - только оригинальная схема

schema - все схемы

параметры - фильтрующие, агрегирующие, лимитирующие, сортирующие выражения и условия, влияющие на ответ сервера.

Параметры запроса

Поддерживаются следующие параметры:

f (find, filter) - JSON выражения для фильтрации списка.

Правила построения фильтров подробно описаны в документации по mongodb
https://docs.mongodb.org/manual/reference/method/db.collection.find/

https://docs.mongodb.org/manual/reference/operator/query/

В запросе НД или строк НД допускается строковый параметр &f= который интерпретируется как поиск по всем индексным полям документов.

Примеры

&f={“nativeId”:1}

nativeId=1

&f={“nativeId”:{“$gte”:1} }

nativeId>=1

&f={“$or”:[{“nativeId”:1}, {“nativeId”:10}]

nativeId=1 || nativeId=10

&f={“nativeId”:1, “odSchema”:”56f7db50658bdacb0a23b0e5”}

nativeId=1 &&odSchema=”56f7db50658bdacb0a23b0e5”

 &f={“data.path.to.field”:”abc”}

{data:{path:{to:{field:”abc”, …}, …}, …}, …}

&f={“data.path.to.array”:{“$in”:[”abc”]}}

Массив data.path.to.array содержит значение “abc”

                

 

o  (order) - строка или JSON  определяющее поле сортировки.

Например

?o=modified - сортировка по возрастанию (можно полностью {“modified”:1} )

?o={“modified”:-1} - сортировка по убыванию

sel (select) -  список полей, разделенный пробелом, которые нужны в ответе, например

?sel=nativeId%20data.regions

По умолчанию возвращаются все доступные поля НД

s (start, skip) - целое число, аналогично SQL LIMIT START, по умолчанию 0.

l (length, limit) -  целое число, аналогично SQL LIMIT. По умолчанию 100.

?s=2&l=5 - возвращает список из 5 документов начниная со 2го

a (aggregate) -

&a=total включается подсчет общего кол-ва, с учетом фильтрации

&a=count - данные не возвращаются, только кол-ов с учетом фильтра

p (populate) - список полей, разделенный пробелом, которые необходимо заполнить субдокументами по прямой ссылке. Такую операцию можно проводить как для единичной ссылки так и для массива субдокументов. Допускает  только для статических связей (для НД, схемы, версии и т.д.).

e (export) - формат выдачи. На данный момент поддерживаются json (по умолчанию), xml, csv

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

attachment: boolean - результат отдается как файл на скачивание (Content-Disposition: attachment )

format : String - формат (json, xml, csv)

encoding : String (по умолчанию “utf8”) - кодировка текста
columnTitle: boolean (по умолчанию false) - флаг добавления заголовка таблицы
delimiter: String (по умолчанию “;”) - разделитель столбцов

rootName : String (по умолчанию “data”) - имя корневой ноды
tagName : String  (по умолчанию имя набора ) - имя ноды документа
includeId : boolean  (по умолчанию false) - флаг включения атрибута-идентификатора документа

Формат ответов в JSON виде

{

  "status": 200, // статус операции

// параметры запроса, как их понял сервер, с учетом значений по умолчанию

  "start": 0,

  "limit": 10,

  "filter": {

    "odSchema": "56f7db50658bdacb0a23b0e5",

    "odSetVersions": {

      "$in": [

        "56f8d202e3de8f2b429de81c"

      ]

    },

    "nativeId": "7704022571"

  },

// количество данных в массиве data (удобно для потокового парсинга)

  "count": 10,

// количество данных, удовлетворяющих условиям без учета параметров пэйджинации (start, limit)

  "total": 215,

// полезная нагрузка ответа всегда приходит в виде массив, даже для тех случаев когда передается 1 сущность

  "data": [ { … payload goes here ….

}, ….]

}

Формат ответа в XML виде (&e=xml)

<?xml version="1.0" encoding="UTF-8"?>

<data>

    <datum id="внутренний идентификатор системы">

        … payload goes here ….

    </datum>

        … etc ….

</data>

Формат ответа в CSV виде (&e=csv)

Для версионированных документов НД, выгрузка производится не полная, а включающая лишь те столбцы данных, которые отмечены для отображения в “человеко-ориентированном” представлении. Метаданные о НД, схемах НД, версиях выгружаются полностью.


Запросы для списка НД

Получение списка доступных наборов данных

GET /v1/

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

Полный пример:

http://opendata.mkrf.ru/v1        

Описание:

Запрос списка названий последних 4х измененных наборов данных

Для комбинации полнотекстового поиска с обычным можно использовать ключ “$text” например
http://host/v1?f={"categories":"5742f27b7b1eac59174c70c7", "$text":"реестр"}

Получение списка всех доступных схем наборов данных

GET /v1/$schemas

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

Полный пример:

http://opendata.mkrf.ru/v1/$schemas?f={"name":{"$regex":"МКРФ"}}&o={"modified":-1}&l=10&sel=name dataset&p=dataset

Описание:

Запрос списка последних 10 измененных схем данных, с заполнением ссылки на набор данных.

Получение списка всех доступных версий наборов данных

GET /v1/$versions

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

Пример:

http://opendata.mkrf.ru/v1$versions?p=dataset&f={"version":3}

Описание:

Запрос списка версий с номером 3, с заполнением ссылок на на набор данных.

Получение списка всех доступных связей наборов данных

GET /v1/$links

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

Пример:

http://opendata.mkrf.ru/v1/$links?f={"linked.odSchema":"56d5659cee48bd2b4b161c16"}

Описание:

Запрос связей, которые установлены для указанной схемы НД.


Запросы к определенному НД

Получение списка версий

GET /v1/<имя НД>

GET /v1/@<dataset._id>

Получение списка версий по заданному НД

Поддерживаются параметры

Примеры

http://opendata.mkrf.ru/v1/subordinates?f={"updateSessions":{"$size":1}}

Получить все версии НД subordinate у которых существует только одна сессия обновления.

Получение списка схем НД

GET /v1/<имя НД>/$schemas

GET /v1/@<dataset._id>/$schemas


Запросы к определенной схеме НД

Получение списка версий НД для заданной схемы

GET /v1/schema/<имя схемы НД>

GET /v1/schema/@<schema._id>

Получение списка версий аналогично списку версий для НД

Пример
http://opendata.mkrf.ru/v1/schema/libraries1


Получение метаданных определенной версии НД

GET /v1/<имя НД>/<номер версии НД>/<тип метаданных>

GET /v1/<имя НД>/@<version._id>/<тип метаданных>

GET /v1/@<dataset._id>/@<version._id>/<тип метаданных>

GET /v1/schema/<имя схемы>/<номер версии НД>/<тип метаданных>

GET /v1/schema/@<schema._id>/@<version._id>/<тип метаданных>

GET /v1/<имя НД>/$/<тип метаданных>

GET /v1/<имя НД>/$first/<тип метаданных>

GET /v1/<имя НД>/$YYYY-MM-DDTHH:MM:SSZ/<тип метаданных>

Получение списка документов в заданной версии НД.

Версия может задаваться

        Номером версии

        Идентификатором версии в системе открытых данных (с префиксом @)

Условием по времени актуализации версии (snapshotTime) внутри схемы НД (с префиксом $):

$ - последняя актуальная версия

$first - первая версия

$2016-01-01 - последняя версия, которая была актуальна на 01 янв 2016

Параметры запроса не поддерживаются

Метаданные о версии НД

GET /v1/<имя НД>/<номер версии НД>/$version

Пример

http://opendata.mkrf.ru/v1/subordinates/1/$version

Метаданные о схеме выбранной версии НД

GET /v1/<имя НД>/<номер версии НД>/$schema

Пример

http://opendata.mkrf.ru/v1/subordinates/1/$schema

Список полей схемы данной версии

GET /v1/<имя НД>/<номер версии НД>/$fields

Возвращает плоский список известных полей схемы данной версии. Каждое поле представлено такой структурой:

{

      "className": имя класса, задающего поведение поля,

      "schema": {

        "title":  краткий заоголовок поля,

        "description": подробное описание поля,

        "type": тип поля в JSON схеме,

        "table": 0 или порядковый номер в табличном представлении

      },

      "path": полный путь (JSON path) к полю в структуре данных,

      "indexable": признак индексации поля

    }

Пример

http://opendata.mkrf.ru/v1/subordinates/1/$fields

В запросе поддерживается простейшая фильтрация (параметр &f= ), позволяющая, например, искать поля определенного типа:

http://opendata.mkrf.ru/v1/subordinates/1/$fields?f={%E2%80%9Cschema.type%E2%80%9D:%E2%80%9Dstring%22}”}

Список индексируемых полей

GET /v1/<имя НД>/<номер версии НД>/$indexes

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

Пример

http://opendata.mkrf.ru/v1/subordinates/1/$indexes

Список полей, включенных в табличное представление

GET /v1/<имя НД>/<номер версии НД>/$table

Поский список полей схемы, которые участвуют в построении человеко-ориентированного табличного представления

Пример

http://opendata.mkrf.ru/v1/subordinates/1/$table

Список связей

GET /v1/<имя НД>/<номер версии НД>/$links 

Возвращает список связей, которые установлены в системе для схемы заданной версии НД

Пример

http://opendata.mkrf.ru/v1/subordinates/1/$links

Получение документов определенной версии НД

GET /v1/<имя НД>/<номер версии НД>/<id or list>

GET /v1/<имя НД>/@<version._id>/@<id or list>

GET /v1/@<dataset._id>/@<version._id>/<id or list>

GET /v1/schema/<имя схемы>/<номер версии НД>/<id or list>

GET /v1/schema/@<schema._id>/@<version._id>/<id or list>

GET /v1/<имя НД>/$/<id or list>

GET /v1/<имя НД>/$first/<id or list>

GET /v1/<имя НД>/$YYYY-MM-DDTHH:MM:SSZ/<id or list>

Где <id or list>  может

Поддерживаются все параметры запроса. Параметр фильтрации (&f=) может быть строкой.

Примеры

Получение списка записей

GET /v1/subordinate/$/

Получение списка записей последней версии

Некорректный поиск

GET /v1/subordinate/$?f={"data.category_institutions":"Завод"}

В ответе поле filter показывает реально сработавшую фильтрацию

Получение записей по списку

GET /v1/subordinate/$/[7704060792,7729124656]

Получение записей по списку идентификаторов исходной системы. Список задается в формате JSON массива

Поик по индексному полю схемы НД

GET /v1/subordinate/$?f={"data.category_institutions":"Библиотека"}

Поиск по нескольким полям

GET /v1/subordinate/$?f={"data.category_institutions":"Библиотека", "data.name":"Рудомино"}

Ограничение списка полей

GET /v1/subordinate/1?sel=nativeId data.general.name

Поля в формате jsonPath разделяются пробелом

Сортировка полю

GET /v1/rokn/1?o={"data.general.region":1}&sel=data.general.region&l=1000

Индекс по полю должен быть определен в схеме, см. $indexes

Сортировка обратная

GET /v1/rokn/1?o={"data.general.region":-1}&sel=data.general.region&l=1000

Наполнение связанных сущностей

GET /v1/subordinate/$?f={"data.name":"заповедник", "data.address":"Москва"}&p=odSchema

Наполнение статически связанных сущностей на примере схемы данных. Разумно при использовании API как backend мобильных приложений или Single Page WebApp

Получение 1 записи

GET  /v1/subordinate/$/7704060792

Получение 1 записи по идентификатору исходной системы 

Получение нескольких документов по списку идентификаторов

http://host/v1/subordinate/$/[7801048166, 7808036089]

Ограничение выборки по длине

GET /v1/subordinate/$?s=50&l=20&o=nativeId

Возвращает список документов упорядоченных по nativeId, состоящий из первых 50 документов начиная с 20


Получение всех версий данных

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

GET /v1/schema/<имя схемы>/$all/<id or list>

GET /v1/schema/@<schema._id>/$all/<id or list>

http://host/v1/schema/@56d543e2180b56f14830c9cf/$all/20319