Wayback CDX API : pagination avec requête wildcard

Problème

Le paramètre de pagination page=N de l'API CDX de la Wayback Machine retourne des résultats vides quand il est combiné avec des requêtes d'URL wildcard (url=domain.com/path/*), même si la même requête sans page= retourne des données. Cela pousse les scripts à rapporter incorrectement « aucun résultat trouvé » alors qu'il y a en réalité des centaines de milliers de résultats.

Contexte / Conditions déclencheurs

• Requête CDX avec url=*.example.com/* ou url=example.com/path/* et page=0 retourne 0 octet
• La même requête sans paramètre page= retourne les données attendues
• Utilisation de l'endpoint API web.archive.org/cdx/search/cdx
• La combinaison matchType=prefix + collapse=urlkey + page=N échoue silencieusement aussi
• Le script fonctionne avec limit=5 mais échoue quand on ajoute page=0

Solution

Option 1 : Utiliser showResumeKey=true (Recommandé)

La méthode de pagination la plus fiable. CDX ajoute un jeton de reprise base64 après un séparateur de ligne vide dans la réponse.

resume_key = None
while True:
    params = {
        'url': 'example.com/path/*',
        'output': 'text',
        'fl': 'original',
        'filter': 'statuscode:200',
        'limit': '10000',
        'showResumeKey': 'true',
    }
    if resume_key:
        params['resumeKey'] = resume_key

    data = fetch_cdx(params)
    if not data:
        break

    # Le jeton de reprise est après la dernière ligne vide
    parts = data.rstrip().rsplit('\n\n', 1)
    if len(parts) == 2:
        data_lines = parts[0].strip().split('\n')
        resume_key = parts[1].strip()
    else:
        data_lines = parts[0].strip().split('\n')
        resume_key = None

    # Traiter data_lines...

    if not resume_key or len(data_lines) < limit:
        break

Option 2 : Utiliser offset=N

Fonctionne mais moins efficace pour les très grands ensembles de résultats.

offset = 0
limit = 10000
while True:
    params = {
        'url': 'example.com/path/*',
        'output': 'text',
        'fl': 'original',
        'limit': str(limit),
        'offset': str(offset),
    }
    data = fetch_cdx(params)
    lines = data.strip().split('\n')
    if not lines or not lines[0]:
        break
    offset += len(lines)

Ce qu'il NE faut PAS faire

# CECI RETOURNE VIDE pour les requêtes wildcard :
params = {
    'url': 'example.com/path/*',
    'page': '0',        # <-- INCOMPATIBLE avec wildcard
    'limit': '10000',
}

# CECI ÉCHOUE AUSSI depuis certaines adresses IP :
params = {
    'url': 'example.com/path/',
    'matchType': 'prefix',
    'collapse': 'urlkey',
    'page': '0',
}

Vérification

• Requête avec showResumeKey=true et sans paramètre page= retourne des données
• La réponse se termine par une ligne vide suivie d'un jeton base64 (le jeton de reprise)
• La requête suivante avec resumeKey=<token> retourne la page suivante

Exemple

Récupérer toutes les URL vine.co/oembed/* (690K+ captures, 312K identifiants vine uniques) :

# Cela fonctionne :
curl "https://web.archive.org/cdx/search/cdx?url=vine.co/oembed/*&output=text&fl=original&limit=10000&showResumeKey=true"

# Cela retourne vide :
curl "https://web.archive.org/cdx/search/cdx?url=vine.co/oembed/*&output=text&fl=original&limit=10000&page=0"

Notes

• page=N fonctionne bien pour les requêtes sans wildcard (p. ex. recherches d'URL exactes)
• L'approche showResumeKey utilise un curseur côté serveur, plus efficace que l'offset
• Maintenir limit à 10000 ou moins pour éviter les timeouts, particulièrement depuis les IPs cloud
• Toujours ajouter time.sleep(3-5) entre les pages pour être courtois envers le serveur CDX
• L'API CDX n'a pas de documentation officielle pour cette incompatibilité

Références

• Docs informelle de l'API CDX : https://github.com/internetarchive/wayback/tree/master/wayback-cdx-server
• Pagination CDX : L'API page a été conçue pour le serveur CDX pywb et peut ne pas être entièrement compatible avec tous les modes de requête sur la Wayback CDX de production