API PubMed: как выгружать данные через E-utilities

• Интерфейс бесплатный, регистрация не обязательна, но ключ API повышает лимит запросов.
• Без ключа — до 3 запросов в секунду, с ключом — до 10.
• esearch возвращает список PMID, efetch — сами записи, esummary — краткие сведения.
• Массовые выгрузки следует делать через FTP-архивы, а не через тысячи запросов к API.
• Аннотации остаются под авторским правом издателей: свободна структура данных, а не их содержание.

Это набор из нескольких точек входа, каждая со своей задачей. Рабочая связка почти всегда одинакова: сначала esearch находит идентификаторы по запросу, затем efetch или esummary получает по этим идентификаторам данные. Запрос в esearch пишется на том же языке, что и в веб-интерфейсе, включая теги полей и операторы, — поэтому стратегию удобно сначала отладить на сайте, а потом перенести в код.

Ограничение по частоте: не более трёх запросов в секунду без ключа и десяти с ключом. Ключ бесплатно выдаётся в настройках аккаунта NCBI. Превышение приводит к ошибкам и, при упорстве, к блокировке адреса.

Второе правило — время: объёмные задания просят выполнять в нерабочие часы по времени восточного побережья США, в выходные или ночью. Третье — идентификация: в запросах указываются параметры tool и email, чтобы NLM мог связаться с вами при проблемах вместо немедленной блокировки. Это не формальность, а способ не потерять доступ.

Если требуется вся база или её крупная часть, обращаться к API тысячами запросов неправильно и медленно. Для этого существуют готовые архивы: ежегодный базовый набор MEDLINE и ежедневные обновления к нему, а также архивы открытой части PMC. Один скачанный файл заменяет десятки тысяч запросов.

Практическое правило: API — для выборок и точечных обращений, FTP-архивы — для массивов. Если ваш скрипт собирается сделать больше нескольких десятков тысяч запросов, почти наверняка нужен архив.

Здесь важно разделить два слоя. Библиографические метаданные — авторы, журнал, год, идентификаторы — можно свободно использовать, хранить и публиковать. Аннотации остаются объектом авторского права издателей: NLM предоставляет к ним доступ, но не передаёт прав на их переиздание и перевод.

Отсюда наш собственный принцип: кластер страниц о PubMed учит пользоваться базой и не является её зеркалом — мы не переводим и не размещаем чужие аннотации, потому что это было бы производным произведением от материалов издателей. Условия, на которых мы публикуем собственные материалы, описаны на странице о лицензии.

Порядок, экономящий время: отладить стратегию поиска в веб-интерфейсе и проверить её через Search details; получить ключ API; реализовать связку esearch → efetch с соблюдением лимита частоты и обязательным повтором при ошибке; сохранять сырые ответы, а не только разобранные поля.

Последнее пригождается чаще, чем кажется: при уточнении задачи разбирать заново придётся те же записи, а повторная выгрузка — это снова часы и снова лимиты. Разбор синтаксиса запросов, который понадобится для esearch, — на странице о расширенном поиске.