Voce: API
API dello strumento di verifica DR: ogni parametro e campo spiegati
Riferimento per la struttura della richiesta e i due campi che ogni risposta autenticata contiene. Le righe specifiche per azione variano, quindi esegui una chiamata di test prima di analizzare i dati.
Il servizio è un'API REST che restituisce JSON. CORS è aperto. Una pagina browser può chiamarla direttamente. Le chiavi iniziano con sk_ e si ottengono dalla pagina dell'account dopo l'accesso con Google.
L'URL base è https://rankupedia.com/api.php. Autenticati con key=sk_... nella query string o con l'intestazione Authorization: Bearer sk_..., a seconda delle preferenze del tuo client. Quattro azioni non richiedono autenticazione: domain, overview, stats e suggest.
Uno strumento di verifica DR è utile solo una volta che sai analizzare il suo output. L'esempio seguente è il caso minimo utile, e le sezioni successive coprono le parti in cui gli utenti commettono errori.
Una chiamata, annotata
L'azione gratuita overview. Sostituisci il dominio con il tuo.
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"Anatomia di una richiesta
Scegli l'azione
Il valore action seleziona l'operazione e il prezzo. Le azioni gratuite sono elencate nella tabella dei costi.
Indica il target
Il valore q è un dominio nudo come nytimes.com, senza schema o percorso.
Aggiungi le credenziali se l'azione è a pagamento
O key nella query string o l'intestazione Bearer. Le intestazioni tengono le chiavi fuori dai log del server e dalla cronologia del browser.
Paginazione e ordinamento
page e per sezionano i risultati e sort con order li ordina. La paginazione si ferma a 50.000 righe.
Preparare l'elenco dei domini prima della prima chiamata
Molti risultati strani derivano dall'input piuttosto che dal server. Pulisci l'elenco una volta, poi invialo.
Rimuovi tutto ciò che non è un dominio nudo. Un indirizzo incollato con un percorso aggiunge caratteri che il valore q non si aspetta, quindi rimuovi lo schema, il percorso e qualsiasi barra finale.
Rimuovi lo schema e il percorso
Trasforma https://shop.example.org/blog/ in shop.example.org prima della chiamata. Il valore q accetta un dominio nudo, quindi il percorso viene scartato qui piuttosto che inviato.
I fogli di calcolo nascondono questi dettagli all'interno di una cella. Un rapido filtro per barre e due punti ne cattura la maggior parte.
Converti i nomi in minuscolo e rimuovi i duplicati
I nomi dei domini non sono sensibili al maiuscolo/minuscolo, quindi Example.COM e example.com indicano un unico target. Inviarli entrambi spende crediti due volte per una sola risposta.
Rimuovi i duplicati prima di contare le chiamate. Un elenco di 2.100 nomi con 300 duplicati richiede due chiamate bulk_dr grezze, ma una volta deduplicato, i suoi 1.800 nomi univui si adattano a una sola chiamata.
Decidere tra il dominio principale e un sottodominio
Un sottodominio come blog.example.org è un nome a sé stante nel tuo elenco. Decidi di quale sottodominio tratta la tua domanda prima di inviare qualsiasi cosa.
Se la domanda riguarda l'intero sito, invia il nome principale. Se riguarda un singolo sottodominio, testa esattamente quel nome e leggi la risposta come appartenente solo a quello.
Scrivi la decisione nelle note del lavoro, così la prossima esecuzione, forse da parte di un'altra persona, applichi la stessa regola.
Parametri di query
| Parametro | Significato | Note |
|---|---|---|
| action | Quale operazione eseguire | Obbligatorio; vedi la tabella dei costi |
| q | Dominio target | Esempio: nytimes.com |
| key | Chiave API | Oppure usa l'intestazione Bearer |
| page | Numero di pagina dei risultati | La paginazione profonda è limitata a 50.000 |
| per | Righe per pagina | Accetta da 10 a 5000; una chiamata è un solo addebito, a qualsiasi numero di righe |
| sort | Colonna per l'ordinamento | Le colonne disponibili dipendono dall'azione |
| order | asc o desc | Usa insieme a sort |
| domains | Elenco per bulk_dr | Max 2.000 domini alla volta, tramite GET o un corpo POST |
Navigare in un elenco lungo
Le azioni di elenco restituiscono righe a pagine. Due parametri controllano la sezione: page seleziona quale sezione, e per imposta quante righe contiene. Per accetta valori da 10 a 5000.
Scegli prima la dimensione della pagina. Un per più grande riduce il numero di chiamate e il fatturato conta le chiamate piuttosto che le righe.
Ordina prima di paginare
Sort e order decidono quali righe finiscono nella pagina uno. Imposta entrambi su ogni chiamata in una serie, così ogni pagina proviene dallo stesso ordinamento.
Usa desc su una colonna metrica quando vuoi le righe più forti per prime, e asc quando cerchi le più deboli. I nomi delle colonne disponibili dipendono dall'azione.
Conferma l'ordine con un piccolo test di due pagine prima di fidarti di un'esecuzione lunga.
Fermati al limite di 50.000 righe
La paginazione profonda si ferma a 50.000 righe. Oltre quel punto la chiamata non restituisce nulla di nuovo, quindi un ciclo che continua a paginare sta sprecando crediti.
Riduci la domanda o dividi il lavoro in esecuzioni più piccole. Una seconda query con un target diverso è solitamente più pulita di una pagina più profonda.
Un limite di profondità è una proprietà dell'elenco, quindi si applica a ogni client che lo chiama.
Termina il ciclo su una pagina breve
Fermati quando una pagina restituisce meno righe di per. Questo è il segno usuale che l'elenco è terminato.
Combina questo test con il controllo del saldo nella voce di risoluzione dei problemi, così il ciclo termina sull'ultima pagina o su un saldo basso, a seconda di ciò che avviene prima.
Campi presenti in ogni risposta
ok
Un booleano. Vero significa che la chiamata è stata completata. Falso significa che non lo è, e lo stato HTTP ti dice il motivo.
_credits
Appare sulle chiamate autenticate. Segnala il costo di questa chiamata e il tuo saldo rimanente in crediti, il che ti permette di fermare un ciclo prima che il saldo si esaurisca.
I nomi dei campi a livello di riga per ogni azione sono visibili in una risposta live. Non li riproduciamo in questa voce affinché non si discosti dal servizio.
Testare una chiamata prima di scrivere un ciclo
Scegli un dominio che conosci
Scegli un sito il cui profilo puoi valutare dalle sue stesse pagine. Un dominio che conosci rende facile individuare un numero strano.
Invia una chiamata gratuita
Esegui overview o domain senza chiave. La risposta mostra la forma reale del JSON, che è più affidabile di qualsiasi descrizione, inclusa questa.
Invia una chiamata a pagamento con la pagina più piccola
Usa per=10 su un'azione di elenco. Vedrai i campi di riga e il valore _credits prima di scalare.
Leggi _credits, poi scala
Moltiplica il costo di una chiamata per il numero di chiamate nel tuo piano. Se il totale è maggiore del saldo, riduci il piano prima che il ciclo inizi.
Prima di distribuire un client
- Controlla ok prima di leggere qualsiasi altro campo
- Registra _credits su ogni chiamata
- Tratta i dati come un'istantanea mensile
- Gestisci 401 e 402 separatamente, vedi la voce di risoluzione dei problemi
- Tieni la chiave fuori dal codice front-end
Note sul batch
L'azione bulk_dr accetta fino a 2.000 domini per chiamata. Inviali come valore di query domains, o come corpo POST quando l'elenco è troppo lungo per un URL.
compare accetta fino a 20 domini e intersect ne accetta da 2 a 10. Intersect risponde a una domanda: quali siti linkano a tutti i domini che indichi.
Poiché il fatturazione è per chiamata, batch più grandi sono sempre più economici per riga. Falliscono anche come unità. Suddividi in chunk di una dimensione che puoi ritentare.
Gli elenchi lunghi possono andare in un corpo POST. Leggi ok prima di qualsiasi altra cosa nella risposta, perché un batch rifiutato non contiene righe che puoi usare.
Leggere il JSON senza presupposti
I parser si rompono sui campi che una risposta omette. Il codice che si aspetta ogni chiave su ogni riga è fragile, e una riga corta può fermare un lavoro intero.
Tratta i campi mancanti come normali
I campi di riga dipendono dall'azione, quindi un campo presente in un elenco può essere assente in un altro. Assegna un valore predefinito a ogni campo e continua.
Registra quale campo era mancante, non solo che qualcosa è fallito. Quel log mostra se lo schema o il tuo codice sono cambiati.
Mantieni le risposte grezze per un campione
Salva il JSON grezzo delle prime poche chiamate in ogni nuovo lavoro. Quando un numero sembra sbagliato in seguito, il testo salvato risolve la domanda più velocemente della memoria.
Archivia il campione con la sua data e il nome dell'azione. Un aggiornamento mensile significa che la stessa chiamata può restituire righe diverse il mese prossimo.
Azioni per famiglia
| Famiglia | Azioni | Uso tipico |
|---|---|---|
| Gratuito | domain, overview, stats, suggest | Consultazioni rapide e autocompletamento |
| Valutazione | bulk_dr, compare, dr_distribution | Selezione di elenchi e set di peer |
| Elenco | refdomains, backlinks, anchors, toppages, anchor_cloud | Audit di un sito |
| Ricerca | search, keyword, intersect | Trovare chi linka con un certo anchor text o a diversi rivali |
I nomi dei campi a livello di riga differiscono per azione e non sono elencati qui. Chiama l'endpoint con un'azione gratuita su un dominio che conosci e leggi il JSON, che è l'unica fonte autorevole.
Domande sui parametri che gli sviluppatori pongono
Quattro domande sui parametri coprono la maggior parte della prima settimana con l'API.
Ho bisogno di una chiave per ogni chiamata?
No. Le azioni domain, overview, stats e suggest non richiedono una chiave. Le azioni a pagamento ne richiedono una, inviata sia come parametro key che come intestazione Bearer.
Posso inviare la chiave nell'URL?
Sì, il parametro key funziona nella query string. L'intestazione tiene la chiave fuori dall'indirizzo stesso, cosa che molti team preferiscono per i log e i link condivisi.
E se voglio per sopra 5000?
L'intervallo documentato è da 10 a 5000. I valori al di fuori di esso rientrano in ciò che questa voce non descrive, quindi mantieni il valore all'interno dell'intervallo e usa la paginazione per ottenere di più.
Il maiuscolo/minuscolo conta in q?
I nomi dei domini non sono sensibili al maiuscolo/minuscolo, quindi converti il valore in minuscolo prima di inviarlo. Una sola ortografia rende i risultati più facili da confrontare tra le esecuzioni.
