Entrée : API
API de l'outil de vérification du DR : chaque paramètre et champ, expliqués
Référence pour la forme de la requête et les deux champs que toute réponse authentifiée contient. Les lignes spécifiques à une action varient, testez donc un appel avant d'analyser la réponse.
Le service est une API REST renvoyant du JSON. CORS est ouvert. Une page web peut l'appeler directement. Les clés commencent par sk_ et sont disponibles sur la page du compte après la connexion Google.
L'URL de base est https://rankupedia.com/api.php. Authentifiez-vous avec key=sk_... dans la chaîne de requête ou avec l'en-tête Authorization: Bearer sk_..., selon la préférence de votre client. Quatre actions n'en ont pas besoin : domain, overview, stats et suggest.
Un outil de vérification du DR n'est utile que si vous pouvez analyser sa sortie. L'exemple ci-dessous est le cas utile le plus simple, et les sections suivantes couvrent les points où les gens se trompent.
Un appel, annoté
L'action gratuite overview. Remplacez le domaine par le vôtre.
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 d'une requête
Choisissez l'action
La valeur action sélectionne l'opération et le prix. Les actions gratuites sont listées dans le tableau des coûts.
Nommez la cible
La valeur q est un domaine nu tel que nytimes.com, sans schéma ni chemin.
Ajoutez les identifiants si l'action est payante
Soit key dans la chaîne de requête, soit l'en-tête Bearer. Les en-têtes maintiennent les clés hors des journaux du serveur et de l'historique du navigateur.
Pagination et tri
page et per découpent les résultats et sort avec order les organise. La pagination s'arrête à 50 000 lignes.
Préparer la liste de domaines avant le premier appel
De nombreux résultats étranges proviennent de l'entrée plutôt que du serveur. Nettoyez la liste une fois, puis envoyez-la.
Supprimez tout ce qui n'est pas un domaine nu. Une adresse collée avec un chemin ajoute des caractères que la valeur q ne prévoit pas, supprimez donc le schéma, le chemin et toute barre oblique finale.
Supprimez le schéma et le chemin
Transformez https://shop.example.org/blog/ en shop.example.org avant l'appel. La valeur q prend un domaine nu, donc le chemin est supprimé ici plutôt qu'envoyé.
Les feuilles de calcul masquent ces détails à l'intérieur d'une cellule. Un filtre rapide pour les barres obliques et les deux-points en attrape la plupart.
Mettez les noms en minuscules et supprimez les doublons
Les noms de domaine ne sont pas sensibles à la casse, donc Example.COM et example.com désignent une seule cible. Envoyer les deux dépense des crédits deux fois pour une seule réponse.
Dédupliquez avant de compter les appels. Une liste de 2 100 noms avec 300 doublons nécessite deux appels bulk_dr bruts, mais une fois dédupliquée, ses 1 800 noms uniques tiennent en un seul appel.
Décidez entre le domaine racine et un sous-domaine
Un sous-domaine tel que blog.example.org est son propre nom dans votre liste. Décidez de ce dont traite votre question avant d'envoyer quoi que ce soit.
Si la question couvre tout le site, envoyez le nom racine. Si elle couvre un seul sous-domaine, testez ce nom exact et lisez la réponse comme appartenant uniquement à ce sous-domaine.
Notez cette décision dans les notes du travail, afin que la prochaine exécution, peut-être par une personne différente, applique la même règle.
Paramètres de requête
| Paramètre | Signification | Notes |
|---|---|---|
| action | Quelle opération exécuter | Requis ; voir le tableau des coûts |
| q | Domaine cible | Exemple : nytimes.com |
| key | Clé API | Ou utilisez l'en-tête Bearer |
| page | Numéro de page des résultats | La pagination profonde est limitée à 50 000 |
| per | Lignes par page | Accepte de 10 à 5000 ; un appel est une facturation, quel que soit le nombre de lignes |
| sort | Colonne par laquelle trier | Les colonnes disponibles dépendent de l'action |
| order | asc ou desc | À utiliser avec sort |
| domains | Liste pour bulk_dr | Max 2 000 domaines à la fois, via GET ou un corps POST |
Parcourir une longue liste
Les actions de liste renvoient des lignes par pages. Deux paramètres contrôlent le découpage : page choisit quelle tranche, et per définit combien de lignes elle contient. Per accepte des valeurs de 10 à 5000.
Choisissez d'abord la taille de page. Un per plus grand réduit le nombre d'appels, et la facturation compte les appels plutôt que les lignes.
Tri avant pagination
Sort et order décident quelles lignes atterrissent sur la page un. Définissez les deux à chaque appel dans une série, afin que chaque page provienne du même ordre.
Utilisez desc sur une colonne de métrique lorsque vous voulez les lignes les plus fortes en premier, et asc lorsque vous cherchez les plus faibles. Les noms de colonnes disponibles dépendent de l'action.
Confirmez l'ordre avec un petit test de deux pages avant de faire confiance à une longue exécution.
Arrêtez-vous à la limite de 50 000 lignes
La pagination profonde s'arrête à 50 000 lignes. Au-delà, l'appel ne renvoie rien de nouveau, donc une boucle qui continue de paginer gaspille des crédits.
Affinez la question ou divisez le travail en exécutions plus petites. Une deuxième requête avec une cible différente est généralement plus propre qu'une page plus profonde.
Une limite de profondeur est une propriété de la liste, donc elle s'applique à chaque client qui l'appelle.
Terminez la boucle sur une page courte
Arrêtez-vous lorsqu'une page renvoie moins de lignes que per. C'est le signe habituel que la liste est épuisée.
Combinez ce test avec la vérification du solde dans l'entrée de dépannage, afin que la boucle se termine sur la dernière page ou sur un solde faible, selon ce qui survient en premier.
Champs présents dans chaque réponse
ok
Un booléen. True signifie que l'appel est terminé. False signifie qu'il ne l'est pas, et le statut HTTP vous dit pourquoi.
_credits
Apparaît sur les appels authentifiés. Il rapporte le coût de cet appel et votre solde restant en crédits, ce qui vous permet d'arrêter une boucle avant que le solde ne soit épuisé.
Les noms de champs au niveau des lignes pour chaque action sont visibles dans une réponse en direct. Nous ne les reproduisons pas dans cette entrée afin qu'elle ne dérive pas du service.
Tester un appel avant d'écrire une boucle
Choisissez un domaine que vous connaissez
Choisissez un site dont le profil vous permet de juger depuis ses propres pages. Un domaine que vous connaissez rend un nombre étrange facile à repérer.
Envoyez un appel gratuit
Exécutez overview ou domain sans clé. La réponse montre la forme réelle du JSON, qui est plus fiable que n'importe quelle description, celle-ci incluse.
Envoyez un appel payant avec la plus petite page
Utilisez per=10 sur une action de liste. Vous verrez les champs de ligne et la valeur _credits avant de passer à l'échelle.
Lisez _credits, puis passez à l'échelle
Multipliez le coût d'un appel par le nombre d'appels dans votre plan. Si le total est supérieur au solde, réduisez le plan avant le début de la boucle.
Avant de déployer un client
- Vérifiez ok avant de lire tout autre champ
- Journalisez _credits à chaque appel
- Traitez les données comme une capture mensuelle
- Gérez 401 et 402 séparément, voir l'entrée de dépannage
- Gardez la clé hors du code front-end
Notes sur le regroupement
L'action bulk_dr accepte jusqu'à 2 000 domaines par appel. Envoyez-les en tant que valeur de requête domains, ou en tant que corps POST lorsque la liste est trop longue pour une URL.
compare prend jusqu'à 20 domaines et intersect en prend 2 à 10. Intersect répond à une seule question : quels sites lient vers tous les domaines que vous nommez.
La facturation étant par appel, les lots plus gros sont toujours moins chers par ligne. Ils échangent aussi en tant qu'unité. Regroupez par une taille que vous pouvez réessayer.
Les longues listes peuvent aller dans un corps POST. Lisez ok avant tout autre élément de la réponse, car un lot rejeté ne contient aucune ligne que vous pouvez utiliser.
Lire le JSON sans hypothèses
Les analyseurs cassent sur les champs qu'une réponse omet. Le code qui s'attend à chaque clé sur chaque ligne est fragile, et une courte ligne peut arrêter tout un travail.
Traitez les champs manquants comme normaux
Les champs de ligne dépendent de l'action, donc un champ présent dans une liste peut être absent d'une autre. Donnez une valeur par défaut à chaque champ et continuez.
Journalisez quel champ manquait, pas seulement qu'une erreur s'est produite. Ce journal montre si le schéma ou votre propre code a changé.
Conservez les réponses brutes pour un échantillon
Enregistrez le JSON brut des premiers appels dans chaque nouveau travail. Lorsqu'un nombre semble faux plus tard, le texte enregistré règle la question plus rapidement que la mémoire.
Stockez l'échantillon avec sa date et le nom de l'action. Un rafraîchissement mensuel signifie que le même appel peut renvoyer des lignes différentes le mois suivant.
Actions par famille
| Famille | Actions | Utilisation typique |
|---|---|---|
| Gratuit | domain, overview, stats, suggest | Recherches rapides et autocomplétion |
| Notation | bulk_dr, compare, dr_distribution | Filtrage de listes et ensembles de pairs |
| Liste | refdomains, backlinks, anchors, toppages, anchor_cloud | Audit d'un site |
| Recherche | search, keyword, intersect | Trouver qui lie avec une ancre donnée ou vers plusieurs concurrents |
Les noms de champs au niveau des lignes diffèrent selon l'action et ne sont pas listés ici. Appelez le point de terminaison avec une action gratuite sur un domaine que vous connaissez et lisez le JSON, qui est la seule source autoritaire.
Questions sur les paramètres que posent les développeurs
Quatre questions sur les paramètres couvrent la plupart de la première semaine avec l'API.
Ai-je besoin d'une clé pour chaque appel ?
Non. Les actions domain, overview, stats et suggest n'ont pas besoin de clé. Les actions payantes en nécessitent une, envoyée soit en tant que paramètre key, soit en tant qu'en-tête Bearer.
Puis-je envoyer la clé dans l'URL ?
Oui, le paramètre key fonctionne dans la chaîne de requête. L'en-tête maintient la clé hors de l'adresse elle-même, ce que beaucoup d'équipes préfèrent pour les journaux et les liens partagés.
Que faire si je veux per supérieur à 5000 ?
La plage documentée est de 10 à 5000. Les valeurs en dehors tombent hors de ce que cette entrée décrit, donc gardez la valeur dans la plage et paginez pour en voir plus.
La casse compte-t-elle dans q ?
Les noms de domaine ne sont pas sensibles à la casse, donc mettez la valeur en minuscules avant de l'envoyer. Une seule orthographe rend les résultats plus faciles à comparer entre les exécutions.
