Sitemap Generation API

Programmatically generate, validate, and deploy XML and HTML sitemaps for your domains. Supports dynamic content, multi-language hreflang tags, and real-time search engine submission.

POST https://api.sitemap.xml/v1/sitemaps/generate

ℹ️

This endpoint triggers an asynchronous generation job. You will receive a webhook notification when the sitemap is ready for download or CDN deployment.

Request Body

Pass a JSON object containing your domain configuration and generation preferences.

Parameter	Type	Required	Description
domain	string	Required	Primary domain to crawl and map (e.g., `example.com`)
format	string	Optional	Output format: `xml`, `html`, or `both`. Defaults to `xml`.
max_urls	integer	Optional	Maximum number of URLs to include. Defaults to 50,000 per sitemap.
include_subdomains	boolean	Optional	Whether to traverse and include subdomains. Defaults to `false`.
priority_rules	object	Optional	Custom priority mapping for path patterns (0.0 to 1.0).
webhook_url	string	Optional	HTTPS endpoint to receive completion events and error reports.

Examples

# Generate XML sitemap for example.com
curl -X POST https://api.sitemap.xml/v1/sitemaps/generate \
  -H "Authorization: Bearer $SITEMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "format": "xml",
    "include_subdomains": true,
    "priority_rules": {
      "/blog/*": 0.8,
      "/products/*": 0.9,
      "/about": 0.5
    }
  }'

import { SitemapClient } from "@sitemap/xml-sdk";

const client = new SitemapClient({apiKey: process.env.SITEMAP_API_KEY});

const job = await client.generate({
  domain: "example.com",
  format: "xml",
  include_subdomains: true,
  webhook_url: "https://hooks.myapp.com/sitemap-ready"
});

console.log(`Job ID: ${job.id}`);

import sitemap_client

client = sitemap_client.Client(api_key="sk_live_...")

job = client.generate(
    domain="example.com",
    format="xml",
    include_subdomains=True,
    priority_rules={"/blog/*": 0.8}
)

print(f"Job started: {job['id']}")

Response

On success, the API returns a job object tracking the generation process.

{
  "id": "job_8x92k3m4p1",
  "status": "queued",
  "domain": "example.com",
  "format": "xml",
  "created_at": "2025-01-15T14:32:00Z",
  "estimated_urls": 12450,
  "cdn_url": null,
  "webhook_status": "pending"
}

HTTP Status Codes

202 Accepted — Job queued for processing

400 Bad Request — Invalid domain or malformed payload

401 Unauthorized — Missing or invalid API key

429 Too Many Requests — Rate limit exceeded

500 Internal Server Error — Service temporarily unavailable

⚠️

Generating sitemaps for domains with >50,000 URLs will automatically split into multiple index files (sitemap-index.xml) to comply with XML sitemap specifications.

Webhook Payload

When generation completes, your webhook endpoint will receive a POST request with the following structure:

{
  "event": "sitemap.generated",
  "job_id": "job_8x92k3m4p1",
  "status": "completed",
  "cdn_url": "https://cdn.sitemap.xml/example.com/sitemap.xml",
  "stats": {
    "total_urls": 12450,
    "indexed_urls": 12380,
    "errors": 70,
    "processing_time_ms": 4230
  }
}