A video sitemap is an XML file that tells Google exactly which videos live on your site and where to find their thumbnail, title, description, and the actual video content. It exists for one reason: Google's crawler is good at reading text but bad at spotting a video buried in JavaScript or served from a player it can't inspect. If your videos aren't showing up in search or in the video carousel, a sitemap is often the cheapest fix.
This guide covers when you actually need one, every tag that matters, a copy-paste XML example, how a sitemap differs from schema, and how to submit and debug it in Search Console.
What a video sitemap is and when you need one
A video sitemap follows the standard sitemaps.org XML protocol but adds a video: namespace with fields specific to video — thumbnail, running time, upload date, and so on. Each entry ties one video to the page URL where it's watchable.
Here's the honest version most tutorials skip: you don't always need one. Google can and does discover videos straight from the page if the video is in the rendered HTML and marked up with VideoObject schema. The sitemap earns its keep in specific situations:
- You host dozens or hundreds of videos and want one file Google can crawl and you can monitor.
- Your videos load via JavaScript or only after a click, so they're not in the initial HTML.
- Videos sit behind a custom player where Google can't reliably find the source file.
- You want the clean Video indexing report in Search Console tied to a single submitted file.
If you have five videos on five well-built pages, skip the sitemap and get video schema markup right instead. If you run a video library, a sitemap is worth the hour it takes to generate. For the bigger picture on how videos earn placement, see our guide to video SEO.
One thing to be clear about: a sitemap helps Google find videos. It does not force indexing, and it won't rank a weak page. Discovery and ranking are different problems.
Required and optional video sitemap tags
Each video is wrapped in a <video:video> block inside a normal <url> entry. Four fields do the heavy lifting; the rest are optional but genuinely useful.
| Tag | Required? | What it does |
|---|---|---|
video:thumbnail_loc |
Yes | URL of the thumbnail image. Must be crawlable. 160×90 to 1920×1080 px. |
video:title |
Yes | Video title. Keep it human, ideally matching the on-page <h1>. |
video:description |
Yes | Up to 2,048 characters. Describe the video, not the page. |
video:content_loc |
One of these two | Direct URL to the raw video file (.mp4, etc.). |
video:player_loc |
One of these two | URL of the embed player (e.g. an iframe player page). |
video:duration |
Recommended | Length in seconds (1 to 28800). Helps eligibility for rich results. |
video:publication_date |
Recommended | When the video went live, in W3C / ISO 8601 format. |
video:family_friendly |
Optional | yes or no. Controls SafeSearch treatment. |
video:view_count |
Optional | Total views. Minor context signal. |
video:tag |
Optional | Up to 32 keyword tags. Distinct from YouTube tags. |
video:live |
Optional | yes for live streams. |
A few rules that trip people up:
- You must supply either
content_locorplayer_loc. Supplying both is fine and often ideal. - The thumbnail must be reachable by Googlebot. If robots.txt blocks the image path, the whole entry usually fails.
- Titles and descriptions in the sitemap should match what's on the page. Google cross-checks, and mismatches erode trust.
A video sitemap XML example
Here's a complete, valid two-video sitemap. Replace the URLs and copy the structure exactly — namespace declaration included.
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
<url>
<loc>https://example.com/guides/onboarding</loc>
<video:video>
<video:thumbnail_loc>https://example.com/thumbs/onboarding.jpg</video:thumbnail_loc>
<video:title>How to onboard your first team in 5 minutes</video:title>
<video:description>A quick walkthrough of adding teammates, setting roles, and inviting your first project.</video:description>
<video:content_loc>https://cdn.example.com/video/onboarding.mp4</video:content_loc>
<video:player_loc>https://example.com/player?id=onboarding</video:player_loc>
<video:duration>312</video:duration>
<video:publication_date>2026-05-14T08:00:00+05:30</video:publication_date>
<video:family_friendly>yes</video:family_friendly>
</video:video>
</url>
<url>
<loc>https://example.com/guides/reporting</loc>
<video:video>
<video:thumbnail_loc>https://example.com/thumbs/reporting.jpg</video:thumbnail_loc>
<video:title>Build a weekly SEO report in 3 clicks</video:title>
<video:description>Turn raw rank data into a shareable report without touching a spreadsheet.</video:description>
<video:content_loc>https://cdn.example.com/video/reporting.mp4</video:content_loc>
<video:duration>428</video:duration>
</video:video>
</url>
</urlset>
A single <url> can hold multiple <video:video> blocks if one page has several videos. Keep each file under 50,000 URLs and 50 MB uncompressed; split into multiple sitemaps and reference them from a sitemap index if you exceed that. Most CMS and video platforms can generate this for you — check before hand-writing hundreds of entries.
Video sitemap vs VideoObject schema
This is the question that stalls most teams. The short answer: they do the same job through different channels, and schema is the better default.
| Video sitemap | VideoObject schema | |
|---|---|---|
| Format | Separate XML file | JSON-LD in the page <head> |
| Delivery | Submitted via Search Console | Crawled with the page |
| Best for | Large libraries, JS-loaded video | Per-page, template-driven sites |
| Monitoring | Sitemaps + Video indexing report | Rich Results Test, Video report |
| Maintenance | One file to keep current | Auto-generated per template |
| Google support | Fully supported | Fully supported |
Google reads both formats and treats them as equivalent sources of metadata. If your CMS renders a VideoObject JSON-LD block on every video page — which most modern setups do — you've already covered the essentials, and a sitemap adds little. Reach for the sitemap when videos aren't in the HTML, or when you specifically want that centralized, monitorable file.
The one case for running both: large sites that want maximum discovery coverage and a single dashboard to watch. There's no penalty for overlap. For the markup itself, our video schema markup walkthrough has the JSON-LD template and the fields Google actually uses.
Submitting and validating in Google Search Console
Once your file is live at a stable URL:
- Upload it to your domain root —
https://yoursite.com/video-sitemap.xmlis the conventional path. - In Google Search Console, open Indexing → Sitemaps.
- Paste the sitemap path and click Submit.
- Optionally add
Sitemap: https://yoursite.com/video-sitemap.xmlto your robots.txt so any crawler can find it.
Google crawls on its own schedule — expect days, not minutes. Come back to the Sitemaps report to confirm it was read with no parse errors, then open the Video indexing report (under Indexing) to see how many videos were actually indexed and, crucially, the named reason for any that weren't.
That report is the whole point. It's the difference between guessing and knowing. Pair it with a rank tracker so you can watch whether newly indexed videos start pulling impressions in the video carousel, not just whether Google saw them.
Quick validation checklist
- XML is well-formed (run it through any XML validator first).
- The
video:namespace is declared on<urlset>. - Every entry has thumbnail, title, description, and content or player URL.
- Thumbnails and video files are not blocked in robots.txt.
- Sitemap URL returns 200, not a redirect or 404.
Troubleshooting videos that won't get indexed
When the Video indexing report shows videos excluded, it names a reason. Here's what the common ones mean and how to fix them.
| Symptom | Likely cause | Fix |
|---|---|---|
| "No video indexed" | Video isn't the page's main content | Move the video above the fold; make it the page's clear focus |
| "Google could not determine the prominent video" | Multiple videos, none dominant | Feature one primary video per page |
| Thumbnail missing | Image blocked or too small | Serve a crawlable thumbnail, 160×90 or larger |
| Video file not crawled | robots.txt disallows the path | Allow the video and thumbnail directories |
| Indexed but no traffic | Weak page relevance | Improve the page and add a transcript |
Three patterns cause the majority of real problems:
The video isn't the main content. Google indexes videos that are the point of the page, not a decorative clip in the sidebar. If your video is an afterthought in the layout, Google treats it that way.
Something is blocked by robots.txt. This catches a surprising number of sites. If Googlebot can't fetch the thumbnail or the video file, the entry silently fails. Test both URLs with the URL Inspection tool.
The video loads only after interaction Google can't perform. Autoplay-on-click players and heavily lazy-loaded embeds can hide the video from the crawler. Make sure the source is present in the rendered HTML, which is exactly where a sitemap's content_loc helps by pointing straight at the file.
If you're still stuck after fixing those, the problem is usually ranking, not indexing — the video is indexed but the page isn't competitive. That's a different job. Our guides on how to rank YouTube videos and broader YouTube SEO cover the relevance and engagement side once discovery is sorted.
The short version
Build video schema first. Add a video sitemap when you have scale, JavaScript-loaded video, or you want a single file to monitor. Get the four required tags right, keep your thumbnails and files unblocked, submit through Search Console, and let the Video indexing report tell you exactly what's wrong. Discovery is the easy part — a clean sitemap removes the excuses so you can focus on making the video worth ranking.