Вхід: 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 вказують на одну ціль. Надсилання обох витрачає кредити двічі за одну відповідь.
Видаліть дублікати перед підрахунком запитів. Список із 2 100 імен із 300 дублікатами вимагає двох викликів bulk_dr у сирому вигляді, але після видалення дублікатів його 1 800 унікальних імен вміщуються в один виклик.
Вирішіть між кореневим доменом та піддоменом
Піддомен, такий як blog.example.org, є окремим іменем у вашому списку. Вирішіть, про який саме йдеться ваше запитання, перш ніж надсилати що-небудь.
Якщо запитання стосується всього сайту, надішліть кореневе ім'я. Якщо ж воно стосується одного піддомену, протестуйте саме це ім'я та сприймайте відповідь як таку, що належить лише йому.
Запишіть рішення в примітки завдання, щоб наступного разу, можливо, інша людина застосувала те саме правило.
Параметри запиту
| Параметр | Значення | Примітки |
|---|---|---|
| action | Яку операцію виконати | Обов'язковий; див. таблицю вартості |
| q | Цільовий домен | Приклад: nytimes.com |
| key | Ключ API | Або використайте заголовок Bearer |
| page | Номер сторінки результатів | Глибока пагінація обмежена 50 000 |
| per | Рядків на сторінку | Приймає значення від 10 до 5000; один виклик — один заряд, незалежно від кількості рядків |
| sort | Стовпець для сортування | Доступні стовпці залежать від дії |
| order | asc або desc | Використовуйте разом із sort |
| domains | Список для bulk_dr | Максимум 2 000 доменів за раз, через 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 приймає до 2 000 доменів за виклик. Надсилайте їх як значення запиту 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?
Імена доменів не чутливі до регістру, тому приведіть значення до нижнього регістру перед надсиланням. Один напис полегшує порівняння результатів між запусками.
