Вход: API
API инструмента проверки DR: каждый параметр и поле разобраны
Справочник по форме запроса и двум полям, которые содержит каждый аутентифицированный ответ. Строки, специфичные для действия, различаются, поэтому перед разбором данных выполните один вызов.
Сервис представляет собой REST API, возвращающий JSON. CORS открыт. Страница браузера может обращаться к нему напрямую. Ключи начинаются с sk_ и получаются на странице аккаунта после входа через Google.
Базовый URL — https://rankupedia.com/api.php. Аутентификация выполняется с помощью key=sk_... в строке запроса или заголовка Authorization: Bearer sk_..., в зависимости от предпочтений вашего клиента. Четыре действия не требуют аутентификации: domain, overview, stats и suggest.
Инструмент проверки DR полезен только тогда, когда вы можете распарсить его вывод. Приведенный ниже пример — минимальный полезный случай, а разделы после него охватывают части, в которых люди часто ошибаются.
Один вызов, с аннотациями
Бесплатное действие overview. Замените домен на свой.
curl "https://rankupedia.com/api.php?action=overview&q=nytimes.com"
# authenticated listing, 100 rows per page:
curl -H "Authorization: Bearer sk_live_..." \
"https://rankupedia.com/api.php?action=refdomains&q=nytimes.com&per=100&page=1&order=desc"Анатомия запроса
Выберите действие
Значение action выбирает операцию и цену. Бесплатные действия перечислены в таблице стоимости.
Укажите цель
Значение q — это чистый домен, такой как nytimes.com, без схемы и пути.
Добавьте учетные данные, если действие платное
Либо key в строке запроса, либо заголовок Bearer. Заголовки исключают ключи из журналов сервера и истории браузера.
Страница и сортировка
page и per разбивают результаты, а sort с order упорядочивают их. Пагинация ограничена 50 000 строк.
Подготовка списка доменов перед первым вызовом
Многие странные результаты начинаются с входных данных, а не с сервера. Очистите список один раз, затем отправьте его.
Удалите все, что не является чистым доменом. Вставленный адрес с путем добавляет символы, которых не ожидает значение q, поэтому удалите схему, путь и любой конечный слэш.
Удалите схему и путь
Преобразуйте https://shop.example.org/blog/ в shop.example.org перед вызовом. Значение q принимает чистый домен, поэтому путь отбрасывается здесь, а не отправляется.
Таблицы скрывают эти детали внутри ячейки. Быстрая фильтрация по слэшам и двоеточиям выявляет большинство из них.
Приведите имена к нижнему регистру и удалите дубликаты
Имена доменов не чувствительны к регистру, поэтому Example.COM и example.com указывают на одну цель. Отправка обоих вариантов тратит кредиты дважды за один ответ.
Удаляйте дубликаты перед подсчетом вызовов. Список из 2100 имен с 300 дубликатами требует двух вызовов bulk_dr в сыром виде, но после удаления дубликатов его 1800 уникальных имен помещаются в один вызов.
Выберите между корневым доменом и поддоменом
Поддомен, такой как blog.example.org, является отдельным именем в вашем списке. Решите, о каком из них идет ваш вопрос, прежде чем что-либо отправлять.
Если вопрос охватывает весь сайт, отправьте корневое имя. Если он охватывает один поддомен, протестируйте это точное имя и прочитайте ответ как относящийся только к нему.
Запишите решение в заметки задачи, чтобы следующий запуск, возможно, другим человеком, применял то же правило.
Параметры запроса
| Параметр | Значение | Примечания |
|---|---|---|
| action | Какую операцию выполнить | Обязательный; см. таблицу стоимости |
| q | Целевой домен | Пример: nytimes.com |
| key | Ключ API | Или используйте заголовок Bearer |
| page | Номер страницы результатов | Глубокая пагинация ограничена 50 000 |
| per | Строк на странице | Принимает значения от 10 до 5000; один вызов — одна оплата, независимо от количества строк |
| sort | Столбец для сортировки | Доступные столбцы зависят от действия |
| order | asc или desc | Используйте вместе с sort |
| domains | Список для bulk_dr | Максимум 2000 доменов за раз, через GET или тело POST |
Прохождение длинного списка
Действия вывода возвращают строки постранично. Два параметра управляют фрагментом: page выбирает фрагмент, а per устанавливает количество строк, которые он содержит. Per принимает значения от 10 до 5000.
Сначала выберите размер страницы. Больший per сокращает количество вызовов, а биллинг учитывает вызовы, а не строки.
Сортируйте перед пагинацией
Sort и order определяют, какие строки попадут на первую страницу. Устанавливайте оба параметра при каждом вызове в серии, чтобы каждая страница имела одинаковый порядок.
Используйте desc для столбца метрики, когда хотите получить самые сильные строки первыми, и asc, когда ищете самые слабые. Доступные имена столбцов зависят от действия.
Подтвердите порядок с помощью небольшого теста двух страниц, прежде чем доверять длинному запуску.
Остановитесь на лимите в 50 000 строк
Глубокая пагинация останавливается на 50 000 строках. За этой точкой вызов не возвращает ничего нового, поэтому цикл, который продолжает пагинацию, тратит кредиты впустую.
Узкий вопрос или разбейте задачу на более мелкие запуски. Второй запрос с другой целью обычно чище, чем более глубокая страница.
Лимит глубины — это свойство вывода, поэтому он применяется к каждому клиенту, который его вызывает.
Завершите цикл на короткой странице
Остановитесь, когда страница вернет меньше строк, чем per. Это обычный признак того, что список исчерпан.
Объедините этот тест с проверкой баланса в записи по устранению неполадок, чтобы цикл завершался на последней странице или при низком балансе, в зависимости от того, что наступит раньше.
Поля, присутствующие в каждом ответе
ok
Логическое значение. True означает, что вызов завершен. False означает, что нет, и статус HTTP указывает причину.
_credits
Появляется при аутентифицированных вызовах. Он сообщает о стоимости этого вызова и вашем оставшемся балансе кредитов, что позволяет остановить цикл до исчерпания баланса.
Имена полей на уровне строки для каждого действия видны в живом ответе. Мы не воспроизводим их в этой записи, чтобы она не расходилась с сервисом.
Тестирование вызова перед написанием цикла
Выберите домен, который вы знаете
Выберите сайт, профиль которого вы можете оценить по его собственным страницам. Домен, который вы знаете, позволяет легко заметить странное число.
Отправьте один бесплатный вызов
Запустите overview или domain без ключа. Ответ покажет реальную форму JSON, которая более надежна, чем любое описание, включая это.
Отправьте один платный вызов с минимальной страницей
Используйте per=10 в действии вывода. Вы увидите поля строк и значение _credits, прежде чем масштабироваться.
Прочитайте _credits, затем масштабируйте
Умножьте стоимость одного вызова на количество вызовов в вашем плане. Если общая сумма больше баланса, уменьшите план до начала цикла.
Перед развертыванием клиента
- Проверяйте ok перед чтением любого другого поля
- Логгируйте _credits при каждом вызове
- Относитесь к данным как к ежемесячному снимку
- Обработайте 401 и 402 отдельно, см. запись по устранению неполадок
- Держите ключ вне кода фронтенда
Примечания о пакетной обработке
Действие bulk_dr принимает до 2000 доменов за вызов. Отправляйте их как значение запроса domains или как тело POST, когда список слишком длинный для URL.
compare принимает до 20 доменов, а intersect — от 2 до 10. Intersect отвечает на один вопрос: какие сайты ссылаются на все указанные вами домены.
Поскольку биллинг начисляется за вызов, более крупные пакеты всегда дешевле на строку. Они также срабатывают как единое целое. Разбивайте на части размером, который можно повторить.
Длинные списки могут быть в теле POST. Прочитайте ok перед чем-либо еще в ответе, потому что отклоненный пакет не содержит строк, которые можно использовать.
Чтение JSON без предположений
Парсеры ломаются на полях, которые ответ оставляет пустым. Код, ожидающий каждый ключ в каждой строке, хрупкий, и одна короткая строка может остановить всю задачу.
Относитесь к отсутствующим полям как к норме
Поля строк зависят от действия, поэтому поле, присутствующее в одном выводе, может отсутствовать в другом. Установите значение по умолчанию для каждого поля и продолжайте.
Логгируйте, какое поле отсутствовало, а не только то, что что-то не сработало. Этот журнал показывает, изменилась ли схема или ваш собственный код.
Сохраняйте исходные ответы для выборки
Сохраняйте исходный JSON первых нескольких вызовов в каждой новой задаче. Когда число позже покажется неверным, сохраненный текст разрешит вопрос быстрее, чем память.
Храните выборку с ее датой и именем действия. Ежемесячное обновление означает, что тот же вызов может возвращать разные строки в следующем месяце.
Действия по семействам
| Семейство | Действия | Типичное использование |
|---|---|---|
| Бесплатные | domain, overview, stats, suggest | Быстрые поиски и автозаполнение |
| Оценивание | bulk_dr, compare, dr_distribution | Отбор списков и наборов сверстников |
| Вывод | refdomains, backlinks, anchors, toppages, anchor_cloud | Аудит одного сайта |
| Поиск | search, keyword, intersect | Поиск того, кто ссылается с данным якорем или на несколько конкурентов |
Имена полей на уровне строки различаются по действию и не перечислены здесь. Вызовите конечную точку с бесплатным действием на домене, который вы знаете, и прочитайте JSON, который является единственным авторитетным источником.
Вопросы по параметрам, которые задают разработчики
Четыре вопроса по параметрам охватывают большую часть первой недели работы с API.
Нужен ли мне ключ для каждого вызова?
Нет. Действия domain, overview, stats и suggest не требуют ключа. Платные действия требуют его, отправляемого либо как параметр key, либо как заголовок Bearer.
Могу ли я отправить ключ в URL?
Да, параметр key работает в строке запроса. Заголовок исключает ключ из самого адреса, что многие команды предпочитают для журналов и общих ссылок.
Что, если я хочу per выше 5000?
Документированный диапазон — от 10 до 5000. Значения вне него выпадают за рамки того, что описывает эта запись, поэтому держите значение в диапазоне и пагинируйте для получения большего.
Влияет ли регистр букв в q?
Имена доменов не чувствительны к регистру, поэтому приведите значение к нижнему регистру перед отправкой. Одна орфография облегчает сравнение результатов между запусками.
