# Sitemap API
> Fetch and parse an XML sitemap (the sitemaps.org protocol). Pass a sitemap URL and the parse endpoint fetches it — following redirects and transparently gunzipping .gz sitemaps — and returns its type: a urlset with every URL and its lastmod, changefreq and priority, or a sitemapindex listing the child sitemaps, with offset/limit paging for large files. The urls endpoint goes further: when the sitemap is an index it fetches the child sitemaps too and flattens every page URL into a single list, with a configurable cap on URLs and child sitemaps and a truncated flag so you stay in control. The request is made server-side and private or internal targets are refused (SSRF-guarded). Built for SEO audits, building crawl queues and content inventories, change monitoring and migration checks. A sitemap fetcher and parser — distinct from generic XML-to-JSON conversion (xml), the robots.txt evaluator (robots) and the on-page SEO audit (seo). No upstream key, no cache.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/sitemap-api/..."
```

## Pricing
- **Free** (Free) — 1,980 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 37,000 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 200,000 calls/Mo, 20 req/s
- **Mega** ($51/Mo) — 780,000 calls/Mo, 50 req/s

## Endpoints

### Sitemap

#### `GET /v1/parse` — Parse a sitemap (urlset/index)

**Parameters:**
- `url` (query, required, string) — Sitemap URL Example: `https://www.oanor.com/sitemap.xml`
- `limit` (query, optional, string) — 1-50000 (default 1000) Example: `10`
- `offset` (query, optional, string) — Paging offset

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sitemap-api/v1/parse?url=https%3A%2F%2Fwww.oanor.com%2Fsitemap.xml&limit=10"
```

**Response:**
```json
{
    "data": {
        "url": "https://www.oanor.com/sitemap.xml",
        "type": "sitemapindex",
        "count": 7,
        "limit": 10,
        "total": 7,
        "offset": 0,
        "sitemaps": [
            {
                "loc": "https://www.oanor.com/sitemap-en.xml",
                "lastmod": null
            },
            {
                "loc": "https://www.oanor.com/sitemap-de.xml",
                "lastmod": null
            },
            {
                "loc": "https://www.oanor.com/sitemap-it.xml",
                "lastmod": null
            },
            {
                "loc": "https://www.oanor.com/sitemap-fr.xml",
                "lastmod": null
            },
            {
                "loc": "https://www.oanor.com/sitemap-es.xml",
                "lastmod": null
            },
            {
                "loc": "https://www.oanor.com/sitemap-nl.xml",
                "lastmod": null
            },
            {
                "loc": "https://www.oanor.com/sitemap-el.xml",
                "lastmod": null
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:39.105Z",
        "request_id": "de418415-ca10-41e6-9416-b86c1882d261"
    },
    "status": "ok",
    "message": "Sitemap parsed",
    "success": true
}
```

#### `GET /v1/urls` — Flatten all URLs (follow index)

**Parameters:**
- `url` (query, required, string) — Sitemap URL Example: `https://www.oanor.com/sitemap.xml`
- `limit` (query, optional, string) — Max URLs (default 2000) Example: `10`
- `max_sitemaps` (query, optional, string) — Max child sitemaps (default 50) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sitemap-api/v1/urls?url=https%3A%2F%2Fwww.oanor.com%2Fsitemap.xml&limit=10&max_sitemaps=1"
```

**Response:**
```json
{
    "data": {
        "url": "https://www.oanor.com/sitemap.xml",
        "urls": [
            "https://www.oanor.com/",
            "https://www.oanor.com/marketplace",
            "https://www.oanor.com/features",
            "https://www.oanor.com/pricing",
            "https://www.oanor.com/categories",
            "https://www.oanor.com/docs",
            "https://www.oanor.com/status",
            "https://www.oanor.com/roadmap",
            "https://www.oanor.com/changelog",
            "https://www.oanor.com/ads"
        ],
        "count": 10,
        "truncated": true,
        "index_size": 7,
        "total_urls": 10,
        "sitemaps_fetched": 1
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:39.951Z",
        "request_id": "00f648c6-f9bf-4a8f-841e-3537ce75be82"
    },
    "status": "ok",
    "message": "URLs flattened",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sitemap-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Fetch and parse an XML sitemap. /v1/parse?url=https://example.com/sitemap.xml fetches the sitemap (following redirects and transparently gunzipping .gz sitemaps) and returns its type — a urlset with every URL and its lastmod, changefreq and priority, or a sitemapindex listing the child sitemaps — with offset/limit paging. /v1/urls fetches a sitemap and, when it is an index, fetches its child sitemaps too and flattens every page URL into one list (with a configurable cap on URLs and child sitemaps, and a truncated flag). The request is made server-side; private/internal targets are refused (SSRF-guarded). Ideal for SEO audits, building crawl queues, content inventories and change monitoring. A sitemap fetcher/parser — distinct from generic XML-to-JSON conversion (xml), the robots.txt evaluator (robots) and the on-page SEO audit (seo). No key, no cache.",
        "spec": "sitemaps.org protocol (urlset + sitemapindex)",
        "endpoints": [
            "/v1/parse",
            "/v1/urls",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:40.051Z",
        "request_id": "3c4ed5ac-d7fd-4ed7-a078-ef7179b30c62"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/sitemap-api
OpenAPI spec: https://www.oanor.com/api/sitemap-api/openapi.json