Video Sitemaps and VideoObject Markup: A Practical Guide

Short answer: Google gives you two ways to describe videos on your own pages, and they do different jobs. VideoObject markup lives inside the page and describes the video. A video sitemap lives in an XML file and lists which page holds which video. According to Google's documentation, VideoObject needs three properties (a name, a thumbnail URL and an upload date), while a video sitemap entry needs a title, a description, a thumbnail and either a content or a player location. Neither one promises that a video will appear in results.

This guide is for developers, SEO specialists and publishers who embed video in their own pages. For the broader picture of video search, read our video SEO and YouTube guide. General sitemap health is a separate topic covered in XML sitemap audit and error fixes. Here the focus stays on video only.

Two tools, two jobs

Google splits its video guidance into three documents: the VideoObject structured data (Opens in a new tab) page, the video sitemaps (Opens in a new tab) page and the general structured data guidelines (Opens in a new tab). They fit together rather than compete. Markup is the page describing its own video. A sitemap is an extra list handed to Google saying where videos live.

Whatever you pick, the video must be on the page

One principle repeats across Google's pages: what you mark up must match what a visitor can see. The general guidelines say not to mark up content that is not visible to readers and to make sure markup is a true representation of the page. The video sitemap page says not to list videos unrelated to the host page. In short, the video should relate to the page topic and a visitor should be able to play it.

VideoObject and video sitemap side by side

Practical suggestion: when video matters to the site, use both. The documents do not forbid combining them, and none of the pages says that one is enough. Which fits better depends on your site structure.

Which situation sounds like yours

1. A handful of videos on hand-managed pages. Markup may be enough, and a sitemap makes discovery easier.
2. Hundreds of videos on templated pages. Adding VideoObject to the template and generating the sitemap automatically scales best.
3. Videos embedded inside articles. This case raises the question many teams ask.

The VideoObject fields that matter

Google's video markup page splits properties into required and recommended groups. The lists below follow its wording. Limits in documentation can change, so check the current page before you build.

Three properties you cannot skip

• name: the title of the video. Each video on your site should have unique text here.
• thumbnailUrl: a URL pointing to the video's unique thumbnail image file.
• uploadDate: the date and time the video was first published, in ISO 8601 format. If you leave out the timezone, Google uses Googlebot's timezone.

Optional fields and what they add

File address or player address

The two are easy to mix up. contentUrl goes straight to the video file, and the documentation stresses that it should not be the page that hosts the video. embedUrl is the address of a player. If you embed from a provider such as YouTube or Vimeo you may not have a file address at all, and embedUrl is the property to use.

Live broadcast markup

Using publication with BroadcastEvent makes isLiveBroadcast, startDate and endDate required. The page tells you to notify the Indexing API when a stream goes live, when it ends after endDate is updated, and when the markup changes. That API supports livestream videos only. If you do not run live streams, skip these properties.

Clip markup for key moments

Clip markup describes parts of a video. Per the page, a Clip needs a name (a descriptive title), a startOffset (seconds from the start) and a url that shares the video's path and carries a time parameter such as ?t=120. endOffset is recommended. The rules: the video must support deep linking to a point other than the start, the whole video must last at least 30 seconds, no two clips for the same video on one page may share a start time, and the page must let people actually watch the video.

Questions before choosing fields

• Do all three required properties exist on every video?
• Does uploadDate carry a timezone?
• If contentUrl is used, does it truly point to the file?
• If Clip is used, is the video at least 30 seconds long with distinct start times?
• Do expiring videos carry an expiry date, and non-expiring ones none?
• Can the thumbnail URL be crawled and indexed?

The last item comes from the general guidelines, which require every image URL in structured data to be crawlable and indexable.

Building a video sitemap entry

In a video sitemap each page is a loc element with videos nested beneath it. Google's page says you can nest several video:video tags inside the loc tag, one for every video on the hosting page.

Mandatory sitemap tags

Which location tag to use

content_loc points to the actual media file and must be a supported format. The page says HTML and Flash are not supported formats. It must not equal the URL in the parent loc tag. player_loc points to a player for one specific video and also must differ from the loc URL. When content_loc is not available, use player_loc.

Extra sitemap tags and their limits

Crawl access conditions

The page states that the URLs must not be disallowed by robots.txt, must be reachable without metafiles and without logging in, must not be blocked by firewalls and must use HTTP or FTP. Streaming protocols are not supported. You may add video tags to an existing sitemap or open a separate video sitemap; the page sets no rule for that choice.

Walking through a sample entry

Example scenario: a hardware store publishes a guide page called "Replacing a tap washer" with one video. The entry holds these values:

The list does not define tag order. Your sitemap generator writes the actual XML. The title and description should echo what the page shows, and the thumbnail URL must not be blocked by robots.txt.

Sitemap entry questions

• Does every video have a title, description, thumbnail and content or player location?
• Is each description within 2048 characters?
• Do content_loc and player_loc differ from loc?
• Are the pages free from robots.txt blocks?
• Are expiry dates current?
• Do the videos relate to the page topic?

Embedded players and where the video sits

Most sites embed video from YouTube. The video sitemap page covers it: for Vimeo, YouTube and other platforms that allow embedding through iframes, player_loc is used rather than content_loc. It even includes a YouTube example with an embed address inside player_loc.

Where to put the player

Practical suggestion: show the video near the top of the content, not inside a tab or a closed accordion. No page demands the very top position. Still, a video that visitors can find at once is easier to verify and more useful to them.

Four checks for embeds

1. Is it visible on load? Practical suggestion: the iframe should be present for a first-time visitor. The documentation does not say how a player that loads only after a click is treated, so do not rely on one. That sitemap URLs must be reachable without a login is a stated condition.
2. Is the thumbnail yours? A custom thumbnail needs an address Google can crawl.
3. Is the player address specific? player_loc must go to the player of one particular video, not to a generic page.
4. Does the page give the video context? The documentation is not explicit here, but the rule against listing unrelated videos implies a topic link between page and video.

Same video on YouTube and on your site

Embedding your own channel's video gives you two pages for the same video, the YouTube watch page and yours. Write them for different jobs. The YouTube description keeps viewers on the channel. Your page gives readers context and extra material around the film.

One page per video, or one video per article?

Teams keep asking: if we add a video to every article, do we need a separate watch page for each? The documentation does not say a separate page is required. The video sitemap page allows several videos on one hosting page and asks for one video:video entry per video.

Questions that settle it

Practical suggestion: ask these questions in order.

1. Is the video the core of the page, or a supporting example? If it is the core, the article page already is the video page. No separate page is needed.
2. Can visitors find and play it easily? If yes, markup and a sitemap entry on that page may be enough.
3. Does the same video appear in several articles? Mark it up on each page where it plays, but do not create duplicate pages without a separate reason.
4. Does the video deserve search interest of its own, with its own topic and query? Then a dedicated page with its own title and description can make sense.

Because the documents set no rule here, treat this as judgment and adapt it to your content.

Using Article and VideoObject together

A page with an article and a video can carry two kinds of markup: Article describes the written piece and VideoObject describes the film. They do not block each other, but each must represent its own item accurately. For article markup see Article and FAQ schema, and for the broader JSON-LD picture see the JSON-LD structured data guide.

Situations and suggested handling

Testing before and after launch

Google's video markup page lays out a rollout sequence. The steps below follow it.

Validate, deploy a few, request a recrawl

1. Validate the markup with the Rich Results Test and fix critical errors.
2. Deploy a few pages and confirm with the URL Inspection tool that Google can access them. They must not be blocked by robots.txt, a noindex tag or a login.
3. Ask Google to recrawl the URLs and submit a sitemap.

The general guidelines add that structured data pages should not be blocked from Googlebot by robots.txt, noindex or any other access control.

Step, tool and expected result

Watching the reports after launch

After the first deployment, the page suggests checking the Rich result status report for more valid items and no increase in invalid ones. Fix problems, inspect live URLs and request validation. After a template or code change, watch for more invalid items or fewer valid ones. Periodically use the Performance report to follow how often pages appear as rich results, clicks and average position. The Search Console API can pull this data automatically. If your interface is not in English, report names may look different.

Manual actions and their scope

The page warns that techniques outside the guidelines may lead to a manual action. Under the general guidelines a structured data manual action removes eligibility for appearing as a rich result, and it does not change how the page ranks in web search. Look for it in the Manual Actions report in Search Console.

Seven traps to avoid

• Marking up a video the page does not show. Markup must be a true representation of the page.
• Pointing contentUrl at the page address. The documentation says not to.
• Using the loc URL as content_loc. The two must differ.
• Blocking the thumbnail in robots.txt. Image URLs must be crawlable.
• Leaving expired videos without an expiry date. If a video expires, say so.
• Writing a sitemap description over 2048 characters. That is the stated limit.
• Rolling out everywhere without a trial. Test on a few pages first.

Keeping data in sync

Markup and sitemap describe the same video in two places, so mismatches creep in easily. A title changes in one place and not the other.

Feed everything from a single record

Practical suggestion: keep the title, description, thumbnail, length and publish date in one record. Let the page template, the VideoObject markup and the sitemap generator read from it. When an editor changes the title, all three update together. Google asks that the sitemap title match the page title and the sitemap description match the page description, and a single source satisfies that without extra effort.

This table is a checking aid for your team, not a table from the documentation.

ISO 8601 and plain seconds

duration uses ISO 8601 (PT1M54S). uploadDate also uses ISO 8601 and should include a timezone. In the sitemap, video:duration is a whole number of seconds from 1 to 28800. Two formats live side by side, so convert in one function inside your template.

Thumbnails and crawlability

The markup page asks for a unique thumbnail per video and refers to separate thumbnail guidelines for details. No size or ratio rule appears on that page, so do not invent one. The one general rule is that the image URL must be crawlable and indexable. If thumbnails sit on a CDN or behind a login, check access with URL Inspection.

A trial rollout on a small site

Example scenario: a regional museum site has 12 exhibition pages and three of them carry an embedded interview film. Rather than touching everything, the team runs a small trial.

1. Inventory. Three page addresses, film titles, thumbnails and lengths go into a sheet. On one page the film is the centrepiece and on two it supports the text.
2. Template. VideoObject is added to the exhibition page template with the required three properties. Because the films are embedded from a provider, embedUrl is used.
3. Sitemap. A separate video sitemap is opened with the three pages, each using player_loc.
4. Validation. One page goes through the Rich Results Test. After fixes, URL Inspection confirms access.
5. Monitoring. The Rich result status report is watched. With no invalid items, the pattern is applied to the other nine pages.

The trial is reversible, so a template mistake never reaches the whole site.

Maintenance when a video is removed or updated

If a video is removed from a page, remove its markup and sitemap entry too. For videos that expire, use expires in markup and video:expiration_date in the sitemap, and only when the video really expires. When you replace a video, refresh the thumbnail, length and description. uploadDate describes when the video was first published, so keep it unless the video is genuinely new. The documentation says nothing further on this point.

The schedule is a suggestion, not a period from the documentation. Rules can change, so check the current pages before you build.

What can go wrong in a trial

Related guides: Video and Discover Visibility for Publishers, How to Read the Google Discover Performance Report, YouTube Video Descriptions and Chapters: Writing Guide.

Conclusion

VideoObject describes the video inside the page, and a video sitemap pairs pages with videos. Google's pages list name, thumbnailUrl and uploadDate as required for markup, with contentUrl, embedUrl, duration, Clip and others as recommended. A sitemap entry needs a title, a description of at most 2048 characters, a thumbnail and a content or player location, and embedded providers such as YouTube use player_loc. The documents do not say that a video in an article needs its own watch page, so the decision follows the role of the video on the page. Trial on a few pages, validate with Google's tools, monitor in Search Console and keep in mind that none of these steps promises rich results or rankings.

If you need help preparing the text for pages and guides that carry video, take a look at the content writing service. Scope and terms are described on the product page.

Frequently Asked Questions

Are a video sitemap and VideoObject markup the same thing?

No. VideoObject is structured data inside the page that describes the video. A video sitemap is a list in an XML file that pairs pages with videos. Google documents them on separate pages and nothing forbids using both.

Which VideoObject properties are required?

According to Google's page, name, thumbnailUrl and uploadDate. uploadDate must be in ISO 8601 format and should include a timezone, otherwise Googlebot's timezone is used. Details can change, so check the current page before you build.

Which tag do I use for a video embedded from YouTube?

The video sitemap page says that for YouTube, Vimeo and other platforms that allow iframe embedding, player_loc is used instead of content_loc. It must point to the player of that specific video and differ from the page's loc URL.

How long can a video sitemap description be?

The page gives a maximum of 2048 characters for video:description. It should match the on-page description, though not necessarily word for word.

If I add a video to an article, do I need a separate video page?

Google's pages do not say so. A video sitemap allows several videos on one hosting page. If the video is the core of the article, the article page may be enough; if the video is a topic of its own, a dedicated page can make sense. The second half is a practical suggestion.

What does Clip markup require?

The page lists name, startOffset and url as required, with endOffset recommended. The video must support deep linking, must last at least 30 seconds, and no two clips for the same video on a page may share a start time.

Does this markup guarantee my video shows up on Google?

No. The documentation describes eligibility and testing steps, not a promise of appearance. Use the Rich Results Test, URL Inspection and Search Console reports to check access and monitor results.