Záznam: API
API nástroje pro kontrolu DR: každý parametr a pole vysvětleno
Odkaz na tvar požadavku a dvě pole, která nese každá autentizovaná odpověď. Řádky specifické pro akci se liší, proto před parsováním otestujte jeden volání.
Služba je REST API vracející JSON. CORS je otevřené. Stránka v prohlížeči může volání provést přímo. Klíče začínají na sk_ a získáte je na stránce účtu po přihlášení přes Google.
Základní URL je https://rankupedia.com/api.php. Ověřte se pomocí key=sk_... v query stringu nebo pomocí hlavičky Authorization: Bearer sk_..., podle toho, co váš klient preferuje. Čtyři akce žádné ověření nepotřebují: domain, overview, stats a suggest.
Nástroj pro kontrolu DR je užitečný až tehdy, když dokážete parsovat jeho výstup. Níže uvedená ukázka je nejmenší užitečný případ a následující sekce pokrývají části, ve kterých lidé často dělají chyby.
Jedno volání, anotované
Bezplatná akce overview. Nahraďte doménu tou vaší.
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"Anatomie požadavku
Nazvěte cíl
Hodnota q je holá doména, například nytimes.com, bez schématu ani cesty.
Přidejte pověření, pokud je akce placená
Buď key v query stringu, nebo Bearer hlavička. Hlavičky drží klíče mimo serverové logy a historii prohlížeče.
Stránkování a řazení
page a per krájí výsledky a sort s order je řadí. Stránkování končí u 50 000 řádků.
Příprava seznamu domén před prvním voláním
Mnoho podivných výsledků začíná vstupem, nikoliv serverem. Seznam jednou vyčistěte, pak ho pošlete.
Odstraňte vše, co není holá doména. Vložená adresa s cestou přidává znaky, které hodnota q neočekává, takže odstraňte schéma, cestu i koncové lomítko.
Odstraňte schéma a cestu
Přeměňte https://shop.example.org/blog/ na shop.example.org před voláním. Hodnota q bere holou doménu, takže se cesta zahodí zde, nikoliv posílá.
Tabulkové kalkulátory tyto detaily skrývají uvnitř buňky. Rychlý filtr na lomítka a dvojtečky zachytí většinu z nich.
Převeďte názvy na malá písmena a odstraňte duplikáty
Názvy domén nejsou citlivé na velikost písmen, takže Example.COM a example.com označují jeden cíl. Odeslání obou vyčerpá kredity dvakrát za jednu odpověď.
Odstraňte duplikáty před počítáním volání. Seznam 2 100 názvů se 300 duplikáty potřebuje dvě volání bulk_dr surově, ale po odstranění duplikátů jeho 1 800 unikátních názvů vejde do jednoho.
Rozhodněte se mezi kořenem a subdoménou
Subdoména jako blog.example.org je ve vašem seznamu vlastní název. Rozhodněte se, o kterou otázku jde, než něco pošlete.
Pokud otázka pokrývá celý web, pošlete kořenový název. Pokud pokrývá jednu subdoménu, otestujte přesně ten název a odpověď čtěte jako příslušející pouze jí.
Zapište rozhodnutí do poznámek úlohy, aby další běh, možná jinou osobou, použil stejné pravidlo.
Parametry dotazu
| Parametr | Význam | Poznámky |
|---|---|---|
| action | Která operace se má spustit | Povinné; viz tabulka cen |
| q | Cílová doména | Příklad: nytimes.com |
| key | API klíč | Nebo použijte Bearer hlavičku |
| page | Číslo stránky výsledků | Hluboké stránkování je omezeno na 50 000 |
| per | Řádků na stránku | Přijímá 10 až 5000; jedno volání je jeden náklad, bez ohledu na počet řádků |
| sort | Sloupec pro řazení | Dostupné sloupce závisí na akci |
| order | asc nebo desc | Používejte společně se sort |
| domains | Seznam pro bulk_dr | Max 2 000 domén najednou, přes GET nebo tělo POST |
Procházení dlouhého výpisu
Akcí výpisu vrací řádky po stránkách. Dva parametry řídí řez: page vybírá, který řez, a per určuje, kolik řádků obsahuje. Per přijímá hodnoty od 10 do 5000.
Nejprve zvolte velikost stránky. Větší per sníží počet volání a fakturace počítá volání, nikoliv řádky.
Seřaďte před stránkováním
Sort a order rozhodují, které řádky se dostanou na první stránku. Nastavte obě hodnoty při každém volání v sérii, aby každá stránka pocházela ze stejného řazení.
Použijte desc na sloupci metriky, když chcete mít nejsilnější řádky první, a asc, když hledáte nejslabší. Dostupné názvy sloupců závisí na akci.
Potvrďte pořadí malým testem dvou stránek, než důvěřujete dlouhému běhu.
Zastavte se u kapacity 50 000 řádků
Hluboké stránkování končí u 50 000 řádků. Za tímto bodem volání vrací nic nového, takže smyčka, která stránkuje dál, plýtvá kredity.
Zúžte otázku nebo rozdělte úlohu na menší běhy. Druhý dotaz s jiným cílem je obvykle čistší než hlubší stránkování.
Kapacita hloubky je vlastností výpisu, takže platí pro každého klienta, který ji volá.
Ukončete smyčku na krátké stránce
Zastavte, když stránka vrátí méně řádků než per. To je obvyklý znak, že výpis došel.
Kombinujte tento test s kontrolou zůstatku v záznamu pro řešení problémů, aby smyčka skončila na poslední stránce nebo při nízkém zůstatku, podle toho, co přijde dříve.
Pole přítomná v každé odpovědi
ok
Logická hodnota. True znamená, že volání bylo dokončeno. False znamená, že ne, a HTTP status vám řekne proč.
_credits
Vyskytuje se u autentizovaných volání. Reportuje náklad tohoto volání a váš zbývající zůstatek v kreditech, což vám umožní zastavit smyčku, než zůstatek dojde.
Názvy polí na úrovni řádku pro každou akci jsou viditelné v živé odpovědi. Nepřepisujeme je v tomto záznamu, aby nemohl od služby odstoupit.
Testování volání před psaním smyčky
Vyberte doménu, kterou znáte
Vyberte web, jehož profil můžete posoudit z jeho vlastních stránek. Doména, kterou znáte, usnadní odhalit podivné číslo.
Pošlete jedno bezplatné volání
Spusťte overview nebo domain bez klíče. Odpověď ukazuje skutečný tvar JSON, což je spolehlivější než jakýkoliv popis, včetně tohoto.
Pošlete jedno placené volání s nejmenší stránkou
Použijte per=10 u akce výpisu. Uvidíte pole řádků a hodnotu _credits, než přejdete na škálování.
Přečtěte _credits, pak škálujte
Vynásobte náklad jednoho volání počtem volání ve vašem plánu. Pokud je celkem více než zůstatek, zmenšete plán před spuštěním smyčky.
Před nasazením klienta
- Zkontrolujte ok před čtením jakéhokoliv jiného pole
- Logujte _credits při každém volání
- Chápejte data jako měsíční snímek
- Zvládněte 401 a 402 zvlášť, viz záznam pro řešení problémů
- Udržujte klíč mimo front-end kód
Poznámky k dávkování
Akce bulk_dr přijímá až 2 000 domén na volání. Pošlete je jako hodnotu query domains nebo jako tělo POST, když je seznam příliš dlouhý na URL.
compare bere až 20 domén a intersect bere 2 až 10. Intersect odpovídá na jednu otázku: které stránky odkazují na všechny domény, které jmenujete.
Protože fakturace je na volání, větší dávky jsou vždy levnější na řádek. Také selhají jako jeden celek. Rozdělte do velikosti, kterou můžete zopakovat.
Dlouhé seznamy mohou jít v těle POST. Přečtěte ok před čímkoliv jiným v odpovědi, protože zamítnutá dávka neobsahuje řádky, které byste mohli použít.
Čtení JSON bez předpokladů
Parsovače selhávají na polích, která odpověď vynechá. Kód, který očekává každý klíč na každém řádku, je křehký, a jeden krátký řádek může zastavit celý úkol.
Chápejte chybějící pole jako normální
Pole řádků závisí na akci, takže pole přítomné v jednom výpisu může chybět v jiném. Přiřaďte každému poli výchozí hodnotu a pokračujte.
Logujte, které pole chybělo, ne jen to, že něco selhalo. Tento log ukáže, zda se změnila schéma, nebo váš vlastní kód.
Uchovávejte surové odpovědi pro vzorek
Uložte surový JSON prvních několika volání v každém novém úkolu. Když později číslo vypadá špatně, uložený text vyřeší otázku rychleji než paměť.
Uložte vzorek s datem a názvem akce. Měsíční obnova znamená, že stejné volání může příští měsíc vrátit jiné řádky.
Akce podle rodiny
| Rodina | Akce | Typické použití |
|---|---|---|
| Bezplatné | domain, overview, stats, suggest | Rychlé dotazy a automatické doplňování |
| Skórování | bulk_dr, compare, dr_distribution | Prohledávání seznamů a souborů peerů |
| Výpis | refdomains, backlinks, anchors, toppages, anchor_cloud | Audit jedné stránky |
| Vyhledávání | search, keyword, intersect | Najít, kdo odkazuje daným anchor textem nebo na několik konkurentů |
Názvy polí na úrovni řádku se liší podle akce a nejsou zde uvedeny. Zavolejte endpoint s bezplatnou akcí na doméně, kterou znáte, a přečtěte JSON, což je jediný autoritativní zdroj.
Otázky o parametrech, které vývojáři kladou
Čtyři otázky o parametrech pokrývají většinu prvního týdne s API.
Potřebuji klíč pro každé volání?
Ne. Akce domain, overview, stats a suggest nepotřebují klíč. Placené akce potřebují, posílaný buď jako parametr key nebo jako Bearer hlavička.
Mohu poslat klíč v URL?
Ano, parametr key funguje v query stringu. Hlavička drží klíč mimo adresu samotnou, což mnoho týmů preferuje pro logy a sdílené odkazy.
Co když chci per nad 5000?
Dokumentovaný rozsah je 10 až 5000. Hodnoty mimo něj jsou mimo to, co tento záznam popisuje, takže udržte hodnotu v rozsahu a stránkujte pro více.
Záleží na velikosti písmen v q?
Názvy domén nejsou citlivé na velikost písmen, takže před odesláním hodnotu převedte na malá písmena. Jedno psaní usnadňuje srovnání výsledků napříč běhy.
