# Sitemap

The sitemap endpoint returns the full sitemap analysis for a monitor, including detected sitemaps, URL counts, and any issues found. This is useful for verifying sitemap health on any [monitor](/docs/api/monitors.md) with the [sitemap check](/docs/features/sitemap-monitoring.md) enabled.

You'll need a [monitor ID](/docs/api/monitors.md) for this endpoint.

**Example request:**

```bash
$ OHDEAR_TOKEN="your API token"
$ curl https://ohdear.app/api/sitemap/1 \
    -H "Authorization: Bearer $OHDEAR_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'
```

All endpoints below follow the same [authentication](/docs/api/introduction.md#authenticate-against-the-api) pattern.

## Get sitemap data
<!-- toc: Get sitemap data -->

<pre>GET /api/sitemap/{monitorId}</pre>

Returns the sitemap check results from the latest completed run. You can also fetch results from a specific past run by passing `run_id` (see [check history](/docs/api/check-history.md)).

**Query parameters:**

- `run_id` (integer, optional) -- return results from a specific run instead of the latest. Get run IDs from the [check history endpoint](/docs/api/check-history.md).

Here's what the response looks like:

```json
{
  "checkUrl": "https://example.com/sitemap.xml",
  "totalIssuesCount": 1,
  "totalUrlCount": 142,
  "hasIssues": true,
  "issues": [],
  "sitemapIndexes": [
    {
      "url": "https://example.com/sitemap.xml",
      "issues": []
    }
  ],
  "sitemaps": [
    {
      "url": "https://example.com/sitemap-pages.xml",
      "urlCount": 42,
      "checkedReachabilityOfAllUrls": true,
      "issuesCount": 0,
      "issues": []
    },
    {
      "url": "https://example.com/sitemap-blog.xml",
      "urlCount": 100,
      "checkedReachabilityOfAllUrls": true,
      "issuesCount": 1,
      "issues": [
        {
          "name": "FailedUrlResponse",
          "url": "https://example.com/blog/deleted-post",
          "responseCode": 404
        }
      ]
    }
  ],
  "run_id": 98765,
  "run_started_at": "2026-03-17T00:30:00+00:00",
  "run_ended_at": "2026-03-17T00:53:58+00:00"
}
```

### Top-level fields

- `checkUrl`: the URL Oh Dear checked for sitemaps (typically `https://yoursite.com/sitemap.xml`)
- `totalIssuesCount`: total number of issues found across all sitemaps and sitemap indexes
- `totalUrlCount`: total number of URLs found across all sitemaps
- `hasIssues`: whether any issues were detected (`true`/`false`)
- `issues`: array of top-level issues (e.g., the check URL couldn't be loaded at all)
- `sitemapIndexes`: array of detected [sitemap indexes](#sitemap-index-fields)
- `sitemaps`: array of detected [sitemaps](#sitemap-fields)
- `run_id`: the ID of the run these results come from
- `run_started_at`: when the run started (ISO 8601, UTC), or `null`
- `run_ended_at`: when the run completed (ISO 8601, UTC)

### Sitemap fields

Each entry in the `sitemaps` array contains:

- `url`: the URL of the sitemap
- `urlCount`: number of URLs listed in this sitemap
- `checkedReachabilityOfAllUrls`: whether Oh Dear verified that every URL in the sitemap is reachable
- `issuesCount`: number of issues found in this sitemap
- `issues`: array of [issue objects](#issue-fields) for this sitemap

### Sitemap index fields

Each entry in the `sitemapIndexes` array contains:

- `url`: the URL of the sitemap index
- `issues`: array of [issue objects](#issue-fields) for this sitemap index

### Issue fields

Each issue contains:

- `name`: the issue type identifier (see [issue types](#issue-types) below)
- Additional fields depending on the issue type (e.g., `url`, `responseCode`)

## Issue types

Oh Dear checks for these sitemap issues:

| Issue name | Description |
|------------|-------------|
| `CouldNotLoadCheckUrl` | The sitemap URL couldn't be loaded at all |
| `CouldNotLoadSitemapIndex` | A sitemap index file couldn't be loaded |
| `SitemapContainsInvalidXml` | The sitemap contains malformed XML |
| `SitemapIsEmpty` | The sitemap exists but contains no URLs |
| `SitemapContainsTooManyUrls` | The sitemap exceeds the maximum URL limit |
| `EmptyUrl` | A URL entry in the sitemap is empty |
| `InvalidUrl` | A URL in the sitemap is malformed |
| `NonUniqueUrl` | The same URL appears more than once |
| `InvalidChangeFrequency` | The `<changefreq>` value is not valid |
| `InvalidPriority` | The `<priority>` value is not valid |
| `FailedUrlResponse` | A URL in the sitemap returned an error response (includes `responseCode`) |

## Error handling

This endpoint returns `422 Unprocessable Entity` when:

- The site does not have a sitemap check enabled
- The sitemap check hasn't run yet
- No sitemap was found for the site