GET /api/sitemap-inspect

Sitemap Inspect

Fetch and inspect a sitemap or sitemap index. Accepts a full sitemap URL or a site URL (auto-resolved to /sitemap.xml). Returns structured sitemap data as JSON.

Query parameters

urlrequiredA site URL or sitemap URL. Site URLs are normalized to /sitemap.xml.

Example request

curl

curl "https://tinyutils.dev/api/sitemap-inspect?url=https://example.com"

JavaScript (fetch)

const res = await fetch(
  "https://tinyutils.dev/api/sitemap-inspect?url=https://example.com"
);
const data = await res.json();

Example response (urlset)

{
  "ok": true,
  "input_url": "https://example.com",
  "sitemap_url": "https://example.com/sitemap.xml",
  "final_url": "https://example.com/sitemap.xml",
  "status": 200,
  "content_type": "application/xml",
  "format": "urlset",
  "sitemaps": [],
  "urls": [
    {
      "loc": "https://example.com/",
      "lastmod": "2026-01-05",
      "changefreq": "daily",
      "priority": "1.0"
    }
  ],
  "xml_truncated": false,
  "entries_truncated": false,
  "meta": {
    "responseTimeMs": 76,
    "cached": false,
    "rateLimitedScope": "global"
  },
  "error": null
}

Example response (sitemap index)

{
  "ok": true,
  "input_url": "https://example.com/sitemap.xml",
  "sitemap_url": "https://example.com/sitemap.xml",
  "final_url": "https://example.com/sitemap.xml",
  "status": 200,
  "content_type": "application/xml",
  "format": "sitemap_index",
  "sitemaps": [
    {
      "loc": "https://example.com/sitemap-pages.xml",
      "lastmod": "2026-01-05"
    }
  ],
  "urls": [],
  "xml_truncated": false,
  "entries_truncated": false,
  "meta": {
    "responseTimeMs": 81,
    "cached": false,
    "rateLimitedScope": "global"
  },
  "error": null
}

Error response

{
  "ok": false,
  "input_url": "https://example.com",
  "sitemap_url": "https://example.com/sitemap.xml",
  "final_url": "https://example.com/sitemap.xml",
  "status": 200,
  "content_type": "text/html; charset=utf-8",
  "format": null,
  "sitemaps": [],
  "urls": [],
  "xml_truncated": false,
  "entries_truncated": false,
  "error": "NON_XML_CONTENT",
  "meta": {
    "responseTimeMs": 64,
    "cached": false,
    "rateLimitedScope": "global"
  }
}

Limits and truncation

Sitemap Inspect reads up to 1,048,576 bytes of XML and returns up to 5,000 parsed entries. Use xml_truncated and entries_truncated to detect when the response is partial.

Error codes

INVALID_URLThe URL is missing or malformed.

BLOCKED_HOSTThe hostname is private, reserved, or internal.

TIMEOUTThe upstream request timed out.

NETWORK_ERRORThe upstream request failed.

REDIRECT_LOOPA redirect loop was detected.

MISSING_LOCATIONA redirect response was missing a valid Location header.

TOO_MANY_REDIRECTSThe redirect chain exceeded 10 hops.

NON_XML_CONTENTThe fetched resource was not XML.

UNSUPPORTED_SITEMAP_FORMATThe XML response was not a sitemap index or urlset.

RATE_LIMITEDThe shared daily request limit was exceeded.

INTERNAL_ERRORAn unexpected server error occurred.

Rate limiting

Requests are rate-limited via a global pool shared with the other public TinyUtils endpoints. Successful results and deterministic redirect/format errors are cached for 60 seconds. When the limit is exceeded, the endpoint returns HTTP 429 with RATE_LIMITED.