fedstatAPIr

English

Пакет для R, который скачивает данные ЕМИСС Росстата: выбираете показатель и фильтры — получаете таблицу. Экономит ⏳ и нервы 😡. Пакет неофициальный.

Установка

install.packages("fedstatAPIr")

Самая свежая версия — с GitHub:

# install.packages("remotes") # если remotes ещё не установлен
remotes::install_github("DenchPokepon/fedstatAPIr")

Быстрый пример

Скачаем индексы потребительских цен (показатель 31074) за январь 2024 года по Приморскому краю: все товары и услуги, к предыдущему месяцу и к январю прошлого года.

Номер показателя берём из адреса страницы, названия фильтров и значений — с самой страницы. Скопируйте код в R или RStudio и выполните целиком:

library(fedstatAPIr)

filters <- list(
    "Год" = "2024",
    "Период" = "Январь",
    "Классификатор объектов административно-территориального деления (ОКАТО)" = "Приморский край",
    "Виды показателя" = c(
        "К предыдущему месяцу",
        "К соответствующему периоду предыдущего года"
    ),
    "Виды товаров и услуг" = "*" # звёздочка — все значения
)

job <- fedstat_download(
    indicator_id = "31074",
    filters = filters,
    cache_dir = "ipc-download" # папка для скачанных частей
)
data <- fedstat_collect(job) # готовая таблица

Получится таблица data из 1 500 строк: 750 товаров и услуг × 2 вида индекса. Так выглядят первые строки главных столбцов (настоящие данные ЕМИСС):

head(data[c("s_grtov", "s_POK", "ObsValue")], 5)
#>                              s_grtov                                       s_POK ObsValue
#> 1                Все товары и услуги                        К предыдущему месяцу   100.72
#> 2                Все товары и услуги К соответствующему периоду предыдущего года   109.31
#> 3                         Все товары                        К предыдущему месяцу   100.87
#> 4                         Все товары К соответствующему периоду предыдущего года   109.81
#> 5 Базовый индекс потребительских цен                        К предыдущему месяцу   100.81

ObsValue — значения показателя, уже числами.
Остальные столбцы ЕМИСС называет своими кодами: здесь s_grtov — товары и услуги, s_POK — вид индекса, s_OKATO — территория. Time — год, PERIOD — период, EI — единица измерения. В столбцах ..._code — коды классификаторов.
Папка ipc-download появится в текущей папке R (в проекте RStudio — в папке проекта). Можно указать и полный путь, например "G:/research/ipc-download". Если cache_dir не указать, пакет предложит создать в текущей папке папку вида fedstat-31074-1a2b3c4d — для тех же фильтров это всегда та же папка, и повторный запуск продолжит в ней без вопроса. В скрипте, запущенном через Rscript, спросить некого: тогда загрузка пойдёт во временную папку R, которая удаляется при закрытии R. Чтобы продолжать загрузку в другой день, укажите cache_dir.

Про фильтры:

несколько значений — через c(): "Год" = c("2023", "2024");
"*" выбирает все значения фильтра;
фильтр, у которого на сайте больше одного значения, нужно указать обязательно. Если забудете, пакет назовёт его в ошибке;
регистр букв и лишние пробелы не важны.

Какие фильтры есть у показателя 🔎

Названия фильтров и значений можно скопировать со страницы показателя на fedstat.ru, из настроек таблицы. Или спросите пакет:

filters <- fedstat_show_filters("31074")

Он перечислит все фильтры с числом значений и примерами и напечатает готовый список filters — тот набор, который сайт показывает при открытии страницы:

#> Indicator 31074: Индексы потребительских цен на товары и услуги
#>
#> Filters and their values (use them in Russian, as written here):
#>   "Год": 25 values: "2002", "2003", "2004", ..., "2026"
#>   "Период": 16 values: "январь", "февраль", "март", ..., "IV квартал"
#>   "Классификатор объектов административно-территориального деления (ОКАТО)": 119 values: "Российс...
#>   "Виды показателя": 9 values: "К декабрю предыдущего года", "К предыдущему кварталу", "К предыду...
#>   "Виды товаров и услуг": 1,105 values: "Все товары и услуги", "Все товары", "Базовый индекс потр...
#>   "Единица измерения": one value, selected automatically: "процент"
#>
#> # The selection the website shows first (768 filter combinations). "*" selects every value.
#> filters <- list(
#>     "Год" = "2024",
#>     "Период" = "*",
#>     "Классификатор объектов административно-территориального деления (ОКАТО)" = c(
#>         "Центральный федеральный округ",
#>         "Белгородская область",
#>         "Брянская область"
#>     ),
#> ...

Этот список — отправная точка. Скопируйте его в свой скрипт и замените значения на нужные вам, например "Год" = c("2023", "2024") или "*" для всех значений. Функция также возвращает этот список, поэтому fedstat_download("31074", filters) скачает его без изменений.

Все значения одного фильтра:

ids <- fedstat_get_data_ids("31074")
ids$filter_value_title[ids$filter_field_title == "Виды товаров и услуг"]

Почему скачиваем по частям 🧩

ЕМИСС строит таблицу из всех сочетаний выбранных значений. 20 лет × 12 месяцев × 90 регионов × 1 000 товаров — это 21,6 миллиона сочетаний. Пусть большинство из них пустые, ЕМИСС всё равно проверяет каждое. Такой запрос часто зависает или обрывается, а заодно замедляет сайт для всех остальных.

fedstat_download() режет запрос на небольшие части, делает паузы между ними и сохраняет каждую готовую часть на диск. ЕМИСС получает лёгкую и ровную нагрузку, а вы — загрузку, которая доходит до конца и продолжается с места остановки.

Пример выше — около 2 200 сочетаний, это всего один запрос. Части нужны для выборок побольше: по умолчанию в одной части до 50 000 сочетаний, а между запросами пауза 30–60 секунд.

Запрос больше 100 000 сочетаний пакет без особой настройки не отправит, а больше 250 000 — не отправит никогда, какой бы функцией вы ни пользовались. Такие запросы почти никогда не удаются, а сайт тормозят всем. fedstat_download() скачает ту же выборку частями.

Если загрузка остановилась 🔁

Запустите тот же код ещё раз — с теми же фильтрами и той же cache_dir. Готовые части пропускаются, скачиваются только оставшиеся. Это работает и после перезапуска R или компьютера.

На один запуск отводится час, включая паузы. Чтобы дать два часа, добавьте в вызов fedstat_download() строку total_time_limit_seconds = 7200.

Проценты в сообщениях — доля обработанных сочетаний, а не оставшееся время.

Готовую загрузку можно открыть позже, даже без интернета:

data <- fedstat_collect("ipc-download")

Одна папка — одна выборка: для других фильтров укажите другую cache_dir.

Что видите → что делать

Сообщения пакета — на английском. Ищите в таблице начало сообщения.

Сообщение	Что случилось	Что делать
`Download time limit reached`	Закончился час на запуск	Запустите тот же код ещё раз
`Automatic recovery stopped`	ЕМИСС не отвечает или отвечает ошибками	Подождите час-другой и запустите тот же код ещё раз
`Fedstat may be checking or restricting access`, `Fedstat refused access`	ЕМИСС ограничивает доступ	Пакет сам выждет паузу. Если загрузка остановилась, проверьте, открывается ли www.fedstat.ru в браузере, и повторите позже
`This download folder is in use by another R session`	С папкой уже работает другая сессия R	Дождитесь её. Если R закрылся с ошибкой, удалите папку `.lock` — путь к ней есть в сообщении
`Fedstat changed the filters`, `Fedstat returned data for values that were not requested`	ЕМИСС изменил фильтры показателя	Начните заново с новой `cache_dir`
`Fedstat renamed some values`, `Fedstat no longer offers some of the values you selected`	ЕМИСС переименовал или убрал отдельные значения	Ничего, загрузка продолжится. Убранные значения покажет `print(job)`
`Some ObsValue values are not numbers`	В данных есть пометки вместо чисел	`fedstat_collect(job, try_to_parse_ObsValue = FALSE)` вернёт значения текстом
`This request has ... filter combinations`	Запрос слишком велик для одного обращения к ЕМИСС	Скачайте через `fedstat_download()` — он разделит выборку на части
`Fedstat returned no data`	В выбранном наборе нет данных (у `fedstat_dictionary()`)	Укажите фильтры, по которым на сайте есть данные
`Unknown argument`	Опечатка в названии настройки	Сверьте написание с `?fedstat_download`

Части раз за разом не скачиваются? Сначала уменьшите размер части: max_nominal_cells_request = 20000, а если не поможет — 10000. Для показателей, где заполнены почти все сочетания, 50 000 бывает слишком много. Запустите тот же вызов с новым значением в той же папке: готовые части сохранятся, а оставшиеся будут скачиваться частями поменьше.

Если и это не помогло, добавьте preview_first = TRUE. Тогда перед каждой частью пакет сначала просит ЕМИСС показать таблицу — как кнопка «Применить» на сайте — и только потом скачивает её. Иногда ЕМИСС отдаёт данные только так. Загрузка станет примерно вдвое дольше. Включить можно и посреди загрузки, в той же папке.

Большие выгрузки

filters = "*" вместо списка выбирает всё: все годы, территории и остальные значения. Это может занять много часов.
max_nominal_cells_request — размер части в сочетаниях, по умолчанию 50 000. Это главная настройка скорости и надёжности, и подбирать её стоит под показатель:
- много пустых сочетаний (например, не каждый товар есть в каждом регионе и месяце) — части почти пустые, и ЕМИСС отвечает на них быстро. Части крупнее заметно ускоряют загрузку: попробуйте 100000. Выше 50 000 пакет предупредит, выше 100 000 нужна ещё настройка allow_large_requests = TRUE (она же отключает предупреждение), больше 250 000 нельзя;
- части не скачиваются или долго ждут ответа — уменьшите до 20000 или 10000. Это помогает чаще, чем preview_first = TRUE.
timeout_seconds = 300 — ждать ответа на запрос до 5 минут вместо 3.
fedstat_collect() загружает всю таблицу в память.

Все настройки и подробности — в справке ?fedstat_download.

Освободить место

Части сами не удаляются. Сохраните таблицу, потом удалите их:

saveRDS(data, "ipc-2024.rds") # сохранить таблицу
fedstat_cleanup(job)          # удалить скачанные части

Сохранённая таблица откроется командой data <- readRDS("ipc-2024.rds").

Как найти показатель

Номер показателя — в адресе его страницы на fedstat.ru. В пакете есть и список показателей (на момент выхода версии), номер — в столбце id:

ind <- fedstat_indicators_names_database
ind[grepl("потребительских цен", ind$title), c("id", "title")]

Свежий список скачает fedstat_indicator_info().

Словарь кодов 📖

Значения многих фильтров (территория, вид товара, вид экономической деятельности и т. п.) берутся из классификаторов. В таблице с данными для каждого такого фильтра есть два столбца: с названиями и с кодами. Их имена задаёт ЕМИСС, и у каждого показателя они свои: в индексах цен из примера выше это, например, s_grtov и s_grtov_code (товары и услуги).

Полный словарь показателя — все коды и названия каждого классификатора, в том числе значений, которых нет в вашей выгрузке, — скачает fedstat_dictionary(). Сначала посмотрите, какие классификаторы в нём есть:

dictionary <- fedstat_dictionary("31074")
unique(dictionary[c("field_id", "field_title")])
#>      field_id                                                             field_title
#> 1       s_POK                                                         Виды показателя
#> 10    s_grtov                                                    Виды товаров и услуг
#> 1115  s_OKATO Классификатор объектов административно-территориального деления (ОКАТО)

field_id — имя столбца в данных. Коды и названия одного классификатора:

dictionary[dictionary$field_id == "s_grtov", c("value_id", "value_title")]
#>    value_id                        value_title
#> 10        1                Все товары и услуги
#> 11        2                         Все товары
#> 12        3 Базовый индекс потребительских цен
#> ...

Здесь в словаре 1 105 товаров и услуг, а в примере выше — 750: в январе 2024 года в Приморском крае были данные не по всем. Словарь берётся из SDMX-выгрузки, а не со страницы показателя, поэтому коды в нём те же, что в столбцах _code.

ЕМИСС отдаёт словарь только вместе с данными, поэтому функция скачивает небольшой кусок данных — сначала набор, который сайт показывает при открытии страницы. Если в нём нет данных, она пробует ещё несколько небольших случайных наборов. Если и это не помогло (Fedstat returned no data), укажите фильтры, по которым на сайте точно есть данные: fedstat_dictionary("31074", filters = filters).

Год, период и единица измерения в словарь не входят: у них нет кодов.

Для опытных пользователей

fedstat_get_data_ids(), fedstat_data_ids_filter(), fedstat_post_data_ids_filtered() и fedstat_parse_sdmx_to_table() — отдельные шаги одного запроса, без деления на части и пауз. Функция fedstat_data_load_with_filters() из версии 1.x работает, но устарела. Для них действуют те же ограничения размера запроса.

У каждой функции есть подробная справка с примерами: ?fedstat_get_data_ids, ?fedstat_data_ids_filter, ?fedstat_post_data_ids_filtered, ?fedstat_parse_sdmx_to_table. Например, fedstat_post_data_ids_filtered() умеет скачивать таблицу и в формате Excel (data_format = "excel"). Что изменилось с 1.x — в MIGRATION.md.

Если ЕМИСС не пускает пакет 🚪

Если пакет получает отказ (Fedstat refused access), а сайт в браузере открывается, ЕМИСС может отсекать программы по заголовку User-Agent. Пакет представляется как fedstatAPIr/<версия>. Задайте User-Agent своего браузера — один раз за сессию R, до загрузки:

httr::set_config(httr::user_agent(
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36"
))

Свой User-Agent браузер покажет на странице вроде «what is my user agent». Для одного вызова можно добавить httr::user_agent("...") прямо в fedstat_download(). Так же передаются и другие сетевые настройки, например прокси: httr::use_proxy("http://proxy.example:8080").

Помощь 💬

Справка: ?fedstat_download, ?fedstat_collect, ?fedstat_show_filters, ?fedstat_dictionary, ?fedstat_cleanup.

Если что-то не работает, откройте issue на GitHub и приложите файл download.log из рабочей папки. Разбираться в нём не нужно; паролей, cookies и токенов в нём нет. Можно написать и на deniskrylovvit@gmail.com.

Поделитесь чеканной монетой :)

Если пакет помогает вам в работе, можно поддержать разработку. Спасибо, что пользуетесь!

Разработка

Буду рад вашему вкладу. Перед коммитом пройдите R CMD check --as-cran. Команды форматирования и проверок — в tools/README.md.