---
title: "Dynamic URL Endpoints"
description: "Use runtime API endpoints to generate dynamic URLs for your sitemap."
canonical_url: "https://nuxtseo.com/docs/sitemap/guides/dynamic-urls"
last_updated: "2026-05-11T10:47:46.737Z"
---

## Introduction

When working with a CMS or external data sources, you may need to generate sitemap URLs dynamically at runtime.

The module supports two types of data sources:

- JSON responses from API endpoints
- XML sitemaps from external sources

## URL Structure Reference

All sitemap URLs follow this structure, whether from JSON endpoints or the `urls` config:

```ts
interface SitemapUrl {
  loc: string // Required: The URL path (e.g., '/blog/my-post')
  lastmod?: string | Date // Optional: Last modified date (ISO 8601 format or Date object)
  changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never'
  priority?: 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1 // Optional: 0.0 to 1.0
  images?: ImageEntry[] // Optional: Array of image objects
  videos?: VideoEntry[] // Optional: Array of video objects
  news?: GoogleNewsEntry // Optional: Google News entry
  _sitemap?: string // Optional: Specify which sitemap this URL belongs to (for multi-sitemap setups)
  _encoded?: boolean // Optional: Mark the URL as already encoded
  _i18nTransform?: boolean // Optional: Automatically transform the URL for all locales
  alternatives?: Array<{ // Optional: For i18n/alternate language URLs
    hreflang: string // Language code (e.g., 'en', 'fr', 'es')
    href: string // Full URL to alternative version
  }>
}
```

## Using External XML Sitemaps

If you have an existing XML sitemap, you can reference it directly in your configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  sitemap: {
    sources: [
      'https://example.com/sitemap.xml',
    ]
  }
})
```

## Dynamic URLs from External APIs

When fetching dynamic URLs from external APIs, you have two main approaches:

1. **Direct source configuration** - Use when the API returns data in the correct format
2. **Custom API endpoint** - Use when you need to transform data or implement caching

### 1. Using Source Configuration

For APIs that require authentication or custom headers, provide sources as an array with fetch options:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  sitemap: {
    sources: [
      // Unauthenticated endpoint
      'https://api.example.com/pages/urls',
      // Authenticated endpoint
      [
        'https://authenticated-api.example.com/pages/urls',
        { headers: { Authorization: 'Bearer <token>' } }
      ]
    ]
  }
})
```

### 2. Creating Custom Endpoints

**Step 1: Create the API endpoint**

Use the [`defineSitemapEventHandler()`](/docs/sitemap/nitro-api/nitro-hooks) helper to create type-safe sitemap endpoints:

<code-group>

```ts [Simple]
import type { SitemapUrlInput } from '#sitemap/types'
// server/api/__sitemap__/urls.ts
import { defineSitemapEventHandler } from '#imports'

export default defineSitemapEventHandler(() => {
  return [
    {
      loc: '/about-us',
      // Specify which sitemap this URL belongs to
      _sitemap: 'pages',
    },
  ] satisfies SitemapUrlInput[]
})
```

```ts [Multiple Sitemaps]
import type { SitemapUrl } from '#sitemap/types'
// server/api/__sitemap__/urls.ts
import { defineSitemapEventHandler } from '#imports'

export default defineSitemapEventHandler(async () => {
  const [posts, pages] = await Promise.all([
    $fetch<{ path: string, slug: string }[]>('https://api.example.com/posts')
      .then(posts => posts.map(p => ({
        loc: `/blog/${p.slug}`, // Transform to your domain structure
        _sitemap: 'posts',
      } satisfies SitemapUrl))),
    $fetch<{ path: string }[]>('https://api.example.com/pages')
      .then(pages => pages.map(p => ({
        loc: p.path,
        _sitemap: 'pages',
      } satisfies SitemapUrl))),
  ])
  return [...posts, ...pages]
})
```

```ts [WordPress Example]
// server/api/__sitemap__/wordpress.ts
import { defineSitemapEventHandler } from '#imports'

export default defineSitemapEventHandler(async () => {
  const posts = await $fetch('https://api.externalwebsite.com/wp-json/wp/v2/posts')

  return posts.map(post => ({
    // Transform external URL to your domain
    loc: `/blog/${post.slug}`, // NOT post.link
    lastmod: post.modified,
    changefreq: 'weekly',
    priority: 0.7,
  }))
})
```

```ts [Dynamic i18n]
import type { SitemapUrl } from '#sitemap/types'
// server/api/__sitemap__/urls.ts
import { defineSitemapEventHandler } from '#imports'

export default defineSitemapEventHandler(async () => {
  const config = useRuntimeConfig()
  const baseUrl = config.public.siteUrl
  const locales = config.public.i18n.locales.map(locale => locale.code)
  const isoLocales = Object.fromEntries(
    config.public.i18n.locales.map(locale => ([locale.code, locale.iso]))
  )

  // Example: Fetch data for each locale
  const apiQueries = locales.map(locale =>
    $fetch(`${config.public.apiEndpoint}/sitemap/${locale}/products`)
  )

  const sitemaps = await Promise.all(apiQueries)

  return sitemaps.flat().map(entry => ({
    // explicit sitemap mapping
    _sitemap: isoLocales[entry.locale],
    loc: `${baseUrl}/${entry.locale}/product/${entry.url}`,
    alternatives: entry.alternates?.map(alt => ({
      hreflang: isoLocales[alt.locale],
      href: `${baseUrl}/${alt.locale}/product/${alt.url}`
    }))
  } satisfies SitemapUrl))
})
```

</code-group>

**Step 2: Configure the endpoint**

Add your custom endpoint to the sitemap configuration:

<code-group>

```ts [Single Sitemap]
export default defineNuxtConfig({
  sitemap: {
    sources: [
      '/api/__sitemap__/urls',
    ]
  }
})
```

```ts [Multiple Sitemaps]
export default defineNuxtConfig({
  sitemap: {
    sitemaps: {
      posts: {
        sources: [
          '/api/__sitemap__/urls/posts',
        ]
      },
      pages: {
        sources: [
          '/api/__sitemap__/urls/pages',
        ]
      }
    }
  }
})
```

</code-group>

## Handling Pre-Encoded URLs

By default, the module automatically encodes URL paths. This handles special characters like spaces and unicode (e.g., emojis, accented characters).

If your API or CMS returns URLs that are already encoded, mark them with `_encoded: true` to prevent double-encoding.

```ts [server/api/__sitemap__/urls.ts]
import { defineSitemapEventHandler } from '#imports'

export default defineSitemapEventHandler(async () => {
  // URLs from your API are already encoded
  const urls = await $fetch<{ path: string }[]>('https://api.example.com/pages')
  // e.g. [{ path: '/products/%24pecial-offer' }, { path: '/blog/%F0%9F%98%85' }]

  return urls.map(url => ({
    loc: url.path,
    _encoded: true,
  }))
})
```

<callout type="info">

When `_encoded: true` is set, the module skips automatic encoding entirely. Make sure your URLs are properly encoded.

</callout>