Entrada: API
API de la herramienta comprobadora de DR: cada parámetro y campo, explicado
Referencia para la estructura de la solicitud y los dos campos que lleva toda respuesta autenticada. Las filas específicas de cada acción varían, así que prueba una llamada antes de analizar los datos.
El servicio es una API REST que devuelve JSON. CORS está abierto. Una página web puede llamarlo directamente. Las claves comienzan con sk_ y se obtienen desde la página de la cuenta tras iniciar sesión con Google.
La URL base es https://rankupedia.com/api.php. Autentícate con key=sk_... en la cadena de consulta o con el encabezado Authorization: Bearer sk_..., según prefiera tu cliente. Cuatro acciones no requieren autenticación: domain, overview, stats y suggest.
Una herramienta comprobadora de DR solo es útil una vez que puedes analizar su salida. El siguiente ejemplo es el caso más sencillo y útil, y las secciones posteriores cubren las partes donde la gente suele equivocarse.
Una llamada, anotada
La acción gratuita overview. Reemplaza el dominio por el tuyo.
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"Anatomía de una solicitud
Elige la acción
El valor de action selecciona la operación y el precio. Las acciones gratuitas se listan en la tabla de costes.
Nombra el objetivo
El valor de q es un dominio desnudo como nytimes.com, sin esquema ni ruta.
Añade credenciales si la acción es de pago
Ya sea key en la cadena de consulta o el encabezado Bearer. Los encabezados mantienen las claves fuera de los registros del servidor y del historial del navegador.
Paginación y ordenación
page y per dividen los resultados y sort con order los ordena. La paginación se detiene a las 50.000 filas.
Preparar la lista de dominios antes de la primera llamada
Muchos resultados extraños comienzan con la entrada en lugar de con el servidor. Limpia la lista una vez y luego envíala.
Elimina cualquier cosa que no sea un dominio desnudo. Una dirección pegada con una ruta añade caracteres que el valor q no espera, así que elimina el esquema, la ruta y cualquier barra final.
Elimina el esquema y la ruta
Convierte https://shop.example.org/blog/ en shop.example.org antes de la llamada. El valor q toma un dominio desnudo, así que la ruta se descarta aquí en lugar de enviarse.
Las hojas de cálculo ocultan estos detalles dentro de una celda. Un filtro rápido para barras y dos puntos captura la mayoría de ellos.
Pon los nombres en minúsculas y elimina los duplicados
Los nombres de dominio no distinguen entre mayúsculas y minúsculas, por lo que Example.COM y example.com apuntan a un mismo objetivo. Enviar ambos gasta créditos dos veces por una sola respuesta.
Elimina duplicados antes de contar las llamadas. Una lista de 2.100 nombres con 300 duplicados necesita dos llamadas bulk_dr en bruto, pero una vez eliminados los duplicados, sus 1.800 nombres únicos caben en una sola.
Decide entre el dominio raíz y un subdominio
Un subdominio como blog.example.org es su propio nombre en tu lista. Decide sobre cuál de ellos trata tu pregunta antes de enviar nada.
Si la pregunta cube todo el sitio, envía el nombre raíz. Si cubre un solo subdominio, prueba ese nombre exacto y lee la respuesta como perteneciente solo a él.
Escribe la decisión en las notas del trabajo, para que la próxima ejecución, quizás por otra persona, aplique la misma regla.
Parámetros de consulta
| Parámetro | Significado | Notas |
|---|---|---|
| action | Qué operación ejecutar | Obligatorio; consulta la tabla de costes |
| q | Dominio objetivo | Ejemplo: nytimes.com |
| key | Clave de la API | O usa el encabezado Bearer |
| page | Número de página de resultados | La paginación profunda está limitada a 50.000 |
| per | Filas por página | Acepta de 10 a 5000; una llamada es un cargo, independientemente del número de filas |
| sort | Columna por la que ordenar | Las columnas disponibles dependen de la acción |
| order | asc o desc | Úsalo junto con sort |
| domains | Lista para bulk_dr | Máximo 2.000 dominios por vez, vía GET o un cuerpo POST |
Navegar por una lista larga
Las acciones de listado devuelven filas en páginas. Dos parámetros controlan la división: page selecciona qué porción y per establece cuántas filas contiene. Per acepta valores de 10 a 5000.
Elige el tamaño de página primero. Un per más grande reduce el número de llamadas y la facturación cuenta llamadas, no filas.
Ordena antes de paginar
Sort y order deciden qué filas aparecen en la página uno. Configura ambos en cada llamada de una serie, para que cada página provenga del mismo orden.
Usa desc en una columna de métrica cuando quieras las filas más fuertes primero, y asc cuando busques las más débiles. Los nombres de columna disponibles dependen de la acción.
Confirma el orden con una pequeña prueba de dos páginas antes de confiar en una ejecución larga.
Detente en el límite de 50.000 filas
La paginación profunda se detiene a las 50.000 filas. Más allá de ese punto, la llamada no devuelve nada nuevo, por lo que un bucle que sigue paginando está gastando créditos.
Reduce la pregunta o divide el trabajo en ejecuciones más pequeñas. Una segunda consulta con un objetivo diferente suele ser más limpia que una página más profunda.
Un límite de profundidad es una propiedad del listado, por lo que se aplica a cada cliente que lo llame.
Termina el bucle en una página corta
Detente cuando una página devuelva menos filas que per. Ese es el signo habitual de que el listado se ha agotado.
Combina esa prueba con la verificación del saldo en la entrada de solución de problemas, para que el bucle termine en la última página o cuando el saldo sea bajo, lo que ocurra primero.
Campos presentes en todas las respuestas
ok
Un booleano. True significa que la llamada se completó. False significa que no, y el estado HTTP te dice por qué.
_credits
Aparece en llamadas autenticadas. Informa del coste de esta llamada y de tu saldo restante en créditos, lo que te permite detener un bucle antes de que se agote el saldo.
Los nombres de campo a nivel de fila para cada acción son visibles en una respuesta en vivo. No los reproducimos en esta entrada para que no se desvíen del servicio.
Probar una llamada antes de escribir un bucle
Elige un dominio que conozcas
Elige un sitio cuyo perfil puedas juzgar desde sus propias páginas. Un dominio que conoces hace que un número extraño sea fácil de detectar.
Envía una llamada gratuita
Ejecuta overview o domain sin clave. La respuesta muestra la forma real del JSON, que es más fiable que cualquier descripción, incluida esta.
Envía una llamada de pago con la página más pequeña
Usa per=10 en una acción de listado. Verás los campos de fila y el valor _credits antes de escalar.
Lee _credits, luego escala
Multiplica el coste de una llamada por el número de llamadas en tu plan. Si el total es mayor que el saldo, reduce el plan antes de que comience el bucle.
Antes de desplegar un cliente
- Verifica ok antes de leer cualquier otro campo
- Registra _credits en cada llamada
- Trata los datos como una instantánea mensual
- Maneja 401 y 402 por separado, consulta la entrada de solución de problemas
- Mantén la clave fuera del código front-end
Notas sobre el procesamiento por lotes
La acción bulk_dr acepta hasta 2.000 dominios por llamada. Envíalos como un valor de consulta domains, o como un cuerpo POST cuando la lista sea demasiado larga para una URL.
compare acepta hasta 20 dominios y intersect toma de 2 a 10. Intersect responde a una pregunta: qué sitios enlazan a todos los dominios que nombras.
Debido a que la facturación es por llamada, lotes más grandes son siempre más baratos por fila. También fallan como una unidad. Divide por un tamaño que puedas reintentar.
Las listas largas pueden ir en un cuerpo POST. Lee ok antes de cualquier otra cosa en la respuesta, porque un lote rechazado no contiene filas que puedas usar.
Leer el JSON sin suposiciones
Los analizadores fallan con campos que una respuesta omite. El código que espera todas las claves en cada fila es frágil, y una fila corta puede detener todo un trabajo.
Trata los campos faltantes como normales
Los campos de fila dependen de la acción, por lo que un campo presente en un listado puede estar ausente en otro. Asigna un valor predeterminado a cada campo y continúa.
Registra qué campo faltaba, no solo que algo falló. Ese registro muestra si cambió el esquema o tu propio código.
Mantén las respuestas originales para una muestra
Guarda el JSON original de las primeras llamadas en cada nuevo trabajo. Cuando un número parezca incorrecto más tarde, el texto guardado resuelve la pregunta más rápido que la memoria.
Almacena la muestra con su fecha y nombre de acción. Una actualización mensual significa que la misma llamada puede devolver filas diferentes el próximo mes.
Acciones por familia
| Familia | Acciones | Uso típico |
|---|---|---|
| Gratuito | domain, overview, stats, suggest | Consultas rápidas y autocompletado |
| Puntuación | bulk_dr, compare, dr_distribution | Filtrado de listas y conjuntos de referencia |
| Listado | refdomains, backlinks, anchors, toppages, anchor_cloud | Auditoría de un sitio |
| Búsqueda | search, keyword, intersect | Encontrar quién enlaza con un anchor determinado o con varios competidores |
Los nombres de campo a nivel de fila difieren por acción y no se listan aquí. Llama al endpoint con una acción gratuita en un dominio que conozcas y lee el JSON, que es la única fuente autorizada.
Preguntas sobre parámetros que hacen los desarrolladores
Cuatro preguntas sobre parámetros cubren la mayor parte de la primera semana con la API.
¿Necesito una clave para cada llamada?
No. Las acciones domain, overview, stats y suggest no necesitan clave. Las acciones de pago necesitan una, enviada ya sea como el parámetro key o como un encabezado Bearer.
¿Puedo enviar la clave en la URL?
Sí, el parámetro key funciona en la cadena de consulta. El encabezado mantiene la clave fuera de la dirección en sí, lo que muchos equipos prefieren para registros y enlaces compartidos.
¿Qué pasa si quiero per por encima de 5000?
El rango documentado es de 10 a 5000. Los valores fuera de él caen fuera de lo que describe esta entrada, así que mantén el valor dentro del rango y usa paginación para más.
¿Importa el uso de mayúsculas y minúsculas en q?
Los nombres de dominio no distinguen entre mayúsculas y minúsculas, así que pon el valor en minúsculas antes de enviarlo. Una sola ortografía facilita comparar los resultados entre ejecuciones.
