Post: API
API för DR Checker-verktyg: varje parameter och fält förklarat
Referens för begärans struktur och de två fält som varje autentiserat svar innehåller. Raderna varierar beroende på åtgärd, så testa ett anrop innan du parserar.
Tjänsten är ett REST API som returnerar JSON. CORS är öppet. En webbsida kan anropa den direkt. Nycklar börjar med sk_ och hämtas från kontosidan efter inloggning med Google.
Bas-URL:en är https://rankupedia.com/api.php. Autentisera med key=sk_... i frågesträngen eller med rubriken Authorization: Bearer sk_..., beroende på vad din klient föredrar. Fyra åtgärder kräver ingen autentisering: domain, overview, stats och suggest.
Ett DR Checker-verktyg är bara användbart när du kan tolka dess utdata. Exemplet nedan är det minsta användbara fallet, och avsnitten efter det täcker de delar folk gör fel i.
Ett anrop, annoterat
Den gratis overview-åtgärden. Ersätt domänen med din egen.
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"Anatomisk uppbyggnad av en begäran
Välj åtgärd
Värdet för action väljer operationen och priset. Gratis åtgärder listas i kostnadstabellen.
Namnge målet
Värdet för q är en ren domän som nytimes.com, utan schema eller sökväg.
Lägg till autentisering om åtgärden är betald
Antingen key i frågesträngen eller Bearer-rubriken. Rubriker håller nycklar borta från serverloggar och webbläsarhistorik.
Sidning och sortering
page och per delar upp resultaten och sort med order ordnar dem. Sidning stoppar vid 50 000 rader.
Förbereda domänlistan före det första anropet
Många konstiga resultat börjar med indata snarare än servern. Rensa listan en gång, skicka sedan den.
Ta bort allt som inte är en ren domän. En klistrad adress med en sökväg lägger till tecken som q-värdet inte förväntar sig, så ta bort schemat, sökvägen och eventuellt efterföljande snedstreck.
Ta bort schemat och sökvägen
Gör om https://shop.example.org/blog/ till shop.example.org före anropet. q-värdet tar en ren domän, så sökvägen släpps här snarare än att skickas.
Kalkylblad döljer dessa detaljer inuti en cell. Ett snabbt filter för snedstreck och kolon fångar de flesta av dem.
Gör namnen till gemener och ta bort dubletter
Domännamn är inte skiftlägeskänsliga, så Example.COM och example.com anger ett mål. Att skicka båda spenderar krediter två gånger för ett svar.
Ta bort dubletter innan du räknar anrop. En lista med 2 100 namn med 300 dubletter kräver två bulk_dr-anrop rått, men när den är deduplicerad rymmer dess 1 800 unika namn i ett.
Välj mellan rot och deldomän
En deldomän som blog.example.org är ett eget namn i din lista. Bestäm vilken som din fråga gäller innan du skickar något.
Om frågan täcker hela webbplatsen, skicka rotnamnet. Om den täcker en deldomän, testa exakt det namnet och läs svaret som tillhör det ensamt.
Skriv beslutet i jobbets anteckningar, så att nästa körning, kanske av en annan person, tillämpar samma regel.
Frågeparametrar
| Parameter | Betydelse | Anteckningar |
|---|---|---|
| action | Vilken operation som ska köras | Krävs; se kostnadstabellen |
| q | Måldomän | Exempel: nytimes.com |
| key | API-nyckel | Eller använd Bearer-rubriken |
| page | Sidnummer för resultat | Djup sidning är begränsad till 50 000 |
| per | Rader per sida | Accepterar 10 till 5000; ett anrop är en avgift, oavsett antal rader |
| sort | Kolumn att sortera efter | Tillgängliga kolumner beror på åtgärden |
| order | asc eller desc | Använd tillsammans med sort |
| domains | Lista för bulk_dr | Max 2 000 domäner varje gång, via GET eller en POST-body |
Sidning genom en lång lista
Listningsåtgärder returnerar rader i sidor. Två parametrar styr delningen: page väljer vilken del, och per anger hur många rader den innehåller. Per accepterar värden från 10 till 5000.
Välj sidstorlek först. Ett större per minskar antalet anrop, och fakturering räknar anrop snarare än rader.
Sortera innan du sidar
Sort och order bestämmer vilka rader som hamnar på sida ett. Ställ in båda vid varje anrop i en serie, så att varje sida kommer från samma ordning.
Använd desc på en metrik-kolumn när du vill ha de starkaste raderna först, och asc när du letar efter de svagaste. De tillgängliga kolumnnamnen beror på åtgärden.
Bekräfta ordningen med ett litet test av två sidor innan du litar på en lång körning.
Stoppa vid 50 000-räntgränsen
Djup sidning stoppar vid 50 000 rader. Efter det punkten returnerar anropet inget nytt, så en slinga som fortsätter att sidning slösar krediter.
Begränsa frågan eller dela upp jobbet i mindre körningar istället. En andra fråga med ett annat mål är vanligtvis renare än en djupare sida.
En gräns för djup är en egenskap hos listningen, så den gäller för varje klient som anropar den.
Avsluta slingan på en kort sida
Stoppa när en sida returnerar färre rader än per. Det är det vanliga tecknet på att listningen har tagit slut.
Kombinera det testet med balanskontrollen i felsökningsposten, så att slingan slutar på den sista sidan eller vid låg balans, vilket som kommer först.
Fält som finns i varje svar
ok
En boolean. True betyder att anropet slutfördes. False betyder att det inte gjorde det, och HTTP-statusen berättar varför.
_credits
Visas på autentiserade anrop. Det rapporterar kostnaden för detta anrop och din återstående balans i krediter, vilket låter dig stoppa en slinga innan balansen tar slut.
Radnivåns fältnamn för varje åtgärd är synliga i ett live-svar. Vi reproducerar dem inte i denna post så att den inte kan avvika från tjänsten.
Testa ett anrop innan du skriver en slinga
Välj en domän du känner till
Välj en webbplats vars profil du kan döma från dess egna sidor. En domän du känner till gör ett konstigt nummer lätt att upptäcka.
Skicka ett gratis anrop
Kör overview eller domain utan nyckel. Svaret visar den verkliga strukturen för JSON, vilket är mer tillförlitligt än någon beskrivning, inklusive denna.
Skicka ett betalt anrop med den minsta sidan
Använd per=10 på en listningsåtgärd. Du kommer att se radfälten och _credits-värdet innan du skalar upp.
Läs _credits, skala sedan upp
Multiplicera kostnaden för ett anrop med antalet anrop i din plan. Om totalen är större än balansen, minska planen innan slingan startar.
Före distribution av en klient
- Kontrollera ok innan du läser något annat fält
- Logga _credits vid varje anrop
- Behandla data som en månatlig ögonblicksbild
- Hantera 401 och 402 separat, se felsökningsposten
- Håll nyckeln borta från front-end-kod
Anteckningar om batchning
Åtgärden bulk_dr accepterar upp till 2 000 domäner per anrop. Skicka dem som ett domains-frågevärde, eller som en POST-body när listan är för lång för en URL.
compare tar upp till 20 domäner och intersect tar 2 till 10. Intersect svarar på en fråga: vilka webbplatser länkar till alla domäner du anger.
Eftersom fakturering är per anrop är större batchar alltid billigare per rad. De misslyckas också som en enhet. Dela upp i en storlek du kan försöka om.
Långa listor kan gå i en POST-body. Läs ok innan något annat i svaret, eftersom en avslagen batch inte innehåller några rader du kan använda.
Läsa JSON utan antaganden
Parsers går sönder på fält som ett svar lämnar ut. Kod som förväntar sig varje nyckel på varje rad är skör, och en kort rad kan stoppa ett helt jobb.
Behandla saknade fält som normalt
Radfält beror på åtgärden, så ett fält som finns i en lista kan vara frånvarande i en annan. Ge varje fält ett standardvärde och fortsätt.
Logga vilket fält som var frånvarande, inte bara att något misslyckades. Den loggen visar om schemat eller din egen kod har ändrats.
Behåll råa svar för ett urval
Spara den råa JSON:n från de första få anropen i varje nytt jobb. När ett nummer senare ser fel ut, avgör den sparade texten frågan snabbare än minnet gör.
Lagra urvalet med dess datum och åtgärdsnamn. En månatlig uppdatering innebär att samma anrop kan returnera olika rader nästa månad.
Åtgärder efter familj
| Familj | Åtgärder | Typiskt användningsområde |
|---|---|---|
| Gratis | domain, overview, stats, suggest | Snabba uppslagningar och autokomplettering |
| Betygssättning | bulk_dr, compare, dr_distribution | Screening av listor och jämförelseset |
| Listning | refdomains, backlinks, anchors, toppages, anchor_cloud | Granskning av en webbplats |
| Sökning | search, keyword, intersect | Att hitta vem som länkar med en viss ankertext eller till flera konkurrenter |
Radnivåns fältnamn skiljer sig åt beroende på åtgärd och listas inte här. Anropa slutpunkten med en gratis åtgärd på en domän du känner till och läs JSON:n, vilket är den enda auktoritativa källan.
Frågor om parametrar som utvecklare ställer
Fyra parametrfrågor täcker de flesta av den första veckan med API:et.
Behöver jag en nyckel för varje anrop?
Nej. Åtgärderna domain, overview, stats och suggest kräver ingen nyckel. Betalda åtgärder kräver en, skickad antingen som key-parametern eller som en Bearer-rubrik.
Kan jag skicka nyckeln i URL:en?
Ja, key-parametern fungerar i frågesträngen. Rubriken håller nyckeln borta från adressen själv, vilket många team föredrar för loggar och delade länkar.
Vad händer om jag vill ha per över 5000?
Det dokumenterade intervallet är 10 till 5000. Värden utanför det hamnar utanför vad denna post beskriver, så håll värdet inom intervallet och sidna för mer.
Spelar bokstavsstorlek roll i q?
Domännamn är inte skiftlägeskänsliga, så gör värdet till gemener innan du skickar det. En stavning gör resultaten lättare att jämföra mellan körningar.
