Upload Endpoint

The upload endpoint generates XML sitemaps from a list of URLs. It handles validation, automatic splitting, XML generation, storage, and optional search engine notification.

Endpoint

POST https://dash.sitemaphost.app/api/sitemap/generate

Request Headers

Request Body

{
  "domain": "sitemap.yoursite.com",
  "sitemapName": "pages",
  "sizeLimit": "gsc-optimized",
  "urls": [
    {
      "loc": "https://yoursite.com/",
      "lastmod": "2024-01-15",
      "changefreq": "daily",
      "priority": 1.0
    }
  ],
  "pingGoogle": true
}

Top-Level Properties

sizeLimit Options

Controls how large sitemaps are split into chunks:

When your URL count exceeds the chunk size, SitemapHost automatically creates multiple sitemap files and a sitemap index that references them all.

Example: 25,000 URLs with "gsc-optimized" creates 25 sitemap files plus a sitemap index.

URL Object Properties

Each object in the urls array describes a single page on your website.

Core Properties

{
  "loc": "https://yoursite.com/blog/my-post",
  "lastmod": "2024-01-15T10:30:00Z",
  "changefreq": "weekly",
  "priority": 0.7
}

Note: Google has stated it ignores changefreq and priority. However, other search engines may still use these fields. The lastmod field is the most important metadata after loc.

Image Properties

Add an images array to include image metadata for Google Images. Each URL can have up to 1,000 images.

{
  "loc": "https://yoursite.com/products/blue-widget",
  "lastmod": "2024-01-15",
  "images": [
    {
      "loc": "https://cdn.yoursite.com/images/blue-widget-front.jpg",
      "title": "Blue Widget - Front View",
      "caption": "Premium blue widget with chrome accents"
    },
    {
      "loc": "https://cdn.yoursite.com/images/blue-widget-side.jpg",
      "title": "Blue Widget - Side View"
    }
  ]
}

See Image Sitemaps for detailed guidance.

Hreflang Properties

Add an hreflang array for international SEO. Each entry specifies an alternate language version of the page.

{
  "loc": "https://yoursite.com/about",
  "lastmod": "2024-01-15",
  "hreflang": [
    { "href": "https://yoursite.com/about", "hreflang": "en" },
    { "href": "https://yoursite.com/es/about", "hreflang": "es" },
    { "href": "https://yoursite.com/fr/about", "hreflang": "fr" },
    { "href": "https://yoursite.com/about", "hreflang": "x-default" }
  ]
}

The x-default value designates the fallback URL for users whose language does not match any listed alternative.

Generated XML output:

<url>
  <loc>https://yoursite.com/about</loc>
  <lastmod>2024-01-15</lastmod>
  <xhtml:link rel="alternate" hreflang="en" href="https://yoursite.com/about"/>
  <xhtml:link rel="alternate" hreflang="es" href="https://yoursite.com/es/about"/>
  <xhtml:link rel="alternate" hreflang="fr" href="https://yoursite.com/fr/about"/>
  <xhtml:link rel="alternate" hreflang="x-default" href="https://yoursite.com/about"/>
</url>

News Properties

Add a news object for Google News sitemaps. Only include pages published within the last 48 hours.

{
  "loc": "https://yoursite.com/news/breaking-story",
  "news": {
    "publication": {
      "name": "Your News Site",
      "language": "en"
    },
    "publication_date": "2024-01-15T10:30:00Z",
    "title": "Breaking: Major Event Happens",
    "keywords": "breaking news, major event"
  }
}

See News Sitemaps for detailed guidance.

Video Properties

Add a video object for Google Video sitemaps.

* Either content_loc or player_loc is required.

{
  "loc": "https://yoursite.com/videos/tutorial",
  "video": {
    "thumbnail_loc": "https://cdn.yoursite.com/thumbs/tutorial.jpg",
    "title": "Product Tutorial",
    "description": "Learn how to use our product in 10 minutes.",
    "content_loc": "https://cdn.yoursite.com/videos/tutorial.mp4",
    "duration": 600,
    "view_count": 12000,
    "publication_date": "2024-01-10T08:00:00Z",
    "tag": ["tutorial", "product", "getting started"]
  }
}

See Video Sitemaps for detailed guidance.

Full Example Request

A complete request with multiple URL types:

curl -X POST https://dash.sitemaphost.app/api/sitemap/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "domain": "sitemap.yoursite.com",
    "sitemapName": "pages",
    "sizeLimit": "gsc-optimized",
    "pingGoogle": true,
    "urls": [
      {
        "loc": "https://yoursite.com/",
        "lastmod": "2024-01-15",
        "priority": 1.0,
        "changefreq": "daily"
      },
      {
        "loc": "https://yoursite.com/products/widget",
        "lastmod": "2024-01-14",
        "images": [
          {
            "loc": "https://cdn.yoursite.com/widget.jpg",
            "title": "Widget Photo"
          }
        ]
      },
      {
        "loc": "https://yoursite.com/about",
        "lastmod": "2024-01-10",
        "hreflang": [
          { "href": "https://yoursite.com/about", "hreflang": "en" },
          { "href": "https://yoursite.com/es/about", "hreflang": "es" }
        ]
      }
    ]
  }'

Success Response

{
  "success": true,
  "data": {
    "domain": "sitemap.yoursite.com",
    "sitemapName": "pages",
    "urlCount": 3,
    "filesGenerated": 1,
    "sitemapUrl": "https://sitemap.yoursite.com/sitemap-pages.xml",
    "indexUrl": "https://sitemap.yoursite.com/sitemap-index.xml",
    "googlePing": {
      "status": "success",
      "pingedAt": "2024-01-15T10:30:05Z"
    },
    "indexNow": {
      "status": "success",
      "urlsSubmitted": 3
    }
  }
}

Response Fields

Error Responses

Validation error (422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid URL: 'not-a-url' is not a valid absolute URL.",
    "details": {
      "field": "urls[0].loc",
      "value": "not-a-url"
    }
  }
}

Domain not found (404)

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Domain 'sitemap.example.com' not found. Add it in your dashboard first."
  }
}

URL budget exceeded (422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "URL count (75000) exceeds your plan limit of 50000. Upgrade your plan or reduce the number of URLs."
  }
}

URL Validation Rules

SitemapHost validates every URL before generating the sitemap:

• loc must be an absolute URL starting with https:// or http://
• loc must not exceed 2,048 characters
• lastmod must be a valid ISO 8601 date (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ)
• priority must be between 0.0 and 1.0
• changefreq must be one of: always, hourly, daily, weekly, monthly, yearly, never
• Image loc values must be valid absolute URLs
• Hreflang codes must be valid ISO 639-1 language codes or x-default
• Total URL count must not exceed your plan's URL budget

Next Steps

• Domains Endpoint -- Domain management API
• Multi-Sitemap Support -- Organize URLs with named sitemaps
• Automatic Splitting -- How splitting works in detail