Redirect checker JSON API

Redirect checker JSON API

The JSON API gives you the same result as the redirect checker, but in a machine-readable format for scripts, monitoring and CI pipelines. It is free and needs no API key or registration.

GET https://redirect-tester.com/api.php?url=example.com&ua=googlebot

Parameters

Response

{
    "url": "http://example.com",
    "ua": "default",
    "result": {
        "hops": [
            { "url": "http://example.com", "status": 301, "time": 45, "type": "http", "error": null },
            { "url": "https://example.com/", "status": 200, "time": 120, "type": "http", "error": null }
        ],
        "error": null,
        "hints": [
            { "level": "info", "code": "hint.no_hsts", "text": "No Strict-Transport-Security (HSTS) header on the final URL." }
        ]
    },
    "error": null
}

• result.hops lists every request in order. The last entry is the final URL.
  • status: the HTTP status code, or null if the request failed (timeout, DNS or TLS error). In that case error contains the reason.
  • time: response time in milliseconds.
  • type: http for a normal HTTP response, meta if this page redirected via a meta refresh.
• result.error is set when the check was aborted: on a redirect loop or after more than 10 hops.
• result.hints contains the analysis. level is error, warning, info or success. code is a stable key you can rely on in your code: hint.final_error, hint.missing_location, hint.chain, hint.temporary, hint.meta_refresh, hint.no_https, hint.no_hsts, hint.ok. text is a human-readable explanation.
• error on the top level is set when the request could not be processed. result is null then.

All texts in text and error are in English. Don't parse them, use code and the status codes instead.

HTTP status codes of the API

Limits

Each request counts as one check. The limit is 60 checks per IP address per 10 minutes, shared with the checkers on the website. CORS is not enabled, so browsers block calls from JavaScript on other websites. Call the API from servers, scripts or CI jobs instead.

Examples

curl

curl "https://redirect-tester.com/api.php?url=example.com&ua=googlebot"

curl and jq

# Status code of the final URL
curl -s "https://redirect-tester.com/api.php?url=example.com" | jq '.result.hops[-1].status'

# The whole chain, one hop per line
curl -s "https://redirect-tester.com/api.php?url=example.com" | jq -r '.result.hops[] | "\(.status) \(.url)"'

# Hint codes only
curl -s "https://redirect-tester.com/api.php?url=example.com" | jq -r '.result.hints[].code'

PHP

<?php
$api = 'https://redirect-tester.com/api.php?' . http_build_query(['url' => 'example.com', 'ua' => 'googlebot']);
// ignore_errors: also read the JSON body of 4xx responses
$context = stream_context_create(['http' => ['ignore_errors' => true, 'timeout' => 30]]);
$data = json_decode(file_get_contents($api, false, $context), true, 512, JSON_THROW_ON_ERROR);

if ($data['error'] !== null) {
    exit('API error: ' . $data['error'] . PHP_EOL);
}
$hops = $data['result']['hops'];
$final = end($hops);
printf("%d hop(s), final status %s: %s\n", count($hops), $final['status'] ?? 'failed', $final['url']);
foreach ($data['result']['hints'] as $hint) {
    echo "[{$hint['level']}] {$hint['code']}\n";
}

JavaScript (Node.js 18+)

const params = new URLSearchParams({ url: 'example.com', ua: 'chrome' });
const res = await fetch(`https://redirect-tester.com/api.php?${params}`);
const data = await res.json();
if (!res.ok) {
    throw new Error(`API ${res.status}: ${data.error}`);
}
const { hops, hints } = data.result;
console.log(hops.map((hop) => hop.status ?? 'failed').join(' -> '));
console.log('Final URL:', hops.at(-1).url);
console.log('Hints:', hints.map((hint) => hint.code));

CI check: fail if the final status is not 200

This shell script checks a list of URLs, for example after a deployment or a domain migration, and exits with an error as soon as one of them does not end on a 200:

#!/bin/sh
set -eu

for url in example.com www.example.com http://example.com/old-page; do
    status=$(curl -fsS -G "https://redirect-tester.com/api.php" --data-urlencode "url=$url" \
        | jq -r '.result.hops[-1].status')
    if [ "$status" != "200" ]; then
        echo "FAIL $url: final status $status" >&2
        exit 1
    fi
    echo "OK   $url"
done

Because of curl -f, the script also fails if the API itself answers with 4xx, for example when the rate limit is reached. Keep the list short enough to stay within 60 checks per 10 minutes. For one-off lists, the bulk redirect checker is the quicker option.