fedstatAPIr

English

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

Установка

install.packages("fedstatAPIr")

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

# install.packages("remotes") # если remotes ещё не установлен
# remotes::install_github("DenchPokepon/fedstatAPIr")
install.packages("fedstatAPIr", repos = c('https://denchpokepon.r-universe.dev', 'https://cloud.r-project.org'))

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

Скачаем индексы потребительских цен (показатель 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

Про фильтры:

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

Названия фильтров и значений можно скопировать со страницы показателя на 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

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

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

Все настройки и подробности — в справке ?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.