How do contentUrl and embedUrl differ in VideoObject?

Definition: In VideoObject markup, contentUrl identifies the URL of the video's actual file bytes. embedUrl identifies the URL of a player for the specific video. Google recommends contentUrl when it is available and documents embedUrl as an alternative.

Key facts

• Google's VideoObject documentation recommends contentUrl when possible because it is the most effective way for Google to fetch video content files.
• Schema.org describes contentUrl as the actual bytes of a media object, including an image file or video file. Its VideoObject page lists the property's value type as URL.
• Google's table says that contentUrl must identify the video file's actual content bytes and gives an .mp4 example, rather than a page URL.
• Google's player property documentation says that embedUrl points to the video player itself and usually corresponds to the src attribute of an embed element.
• Schema.org defines embedUrl as a URL pointing to a player for a specific video and distinguishes it from the content of the loc tag.

What does contentUrl identify?

Google's required properties table defines contentUrl as a URL pointing to the video file's actual content bytes, in one of the supported file types. The same table says not to link to the page where the video lives. The value therefore names the file resource that contains the video data.

Google gives this example value:

"contentUrl": "https://www.example.com/video/123/file.mp4"

Schema.org's VideoObject vocabulary describes contentUrl as the actual bytes of the media object, with a video file given as an example. Google also says that this property is the most effective way for it to fetch the video content files when it is available.

What does embedUrl identify?

Google's definition of embedUrl says that it points to a player for the specific video. The URL must be the video player itself, rather than the page where the video lives, and Google says it is usually the value in an embed element's src attribute.

Schema.org makes the same distinction: embedUrl points to a player for a specific video, and its general description refers to the src element of an embed tag. It says that this value should not be the same as the content of the loc tag.

Google gives this example value for the player URL:

"embedUrl": "https://www.example.com/embed/123"

Can both properties appear together?

Yes. Google's standard VideoObject example includes both properties, with a file URL under contentUrl and a player URL under embedUrl:

"contentUrl": "https://www.example.com/video/123/file.mp4",
"embedUrl": "https://www.example.com/embed/123"

The two values describe different resources. Google recommends supplying contentUrl when possible; its table names embedUrl as the alternative when contentUrl is unavailable. Schema.org's separate definitions preserve the same distinction between media bytes and a player.

How can you check the values?

Read the target of each URL according to the definitions above. A contentUrl value should identify the video file's actual bytes, while an embedUrl value should identify the player for that video. A page URL that merely contains the player is not the documented target for either property: Google specifies the file itself for contentUrl and the player itself for embedUrl.

Related terms

• What thumbnail data does Google require for VideoObject markup?
• How do I add key moments to a video with structured data?
• How is video duration expressed in structured data?
• Which BroadcastEvent fields are required for a live video badge?

FAQ

Can embedUrl replace contentUrl?

Google documents embedUrl as an alternative when contentUrl is unavailable. When the direct video file URL exists, Google recommends providing contentUrl because it is the most effective way to fetch the video content files.

Should contentUrl point to the watch page?

No. Google's contentUrl guidance says to use the URL of the video file's actual content bytes and not the page where the video lives.

Should embedUrl point to the watch page?

No. Google's guidance says that embedUrl must be the URL of the video player itself. Schema.org describes it as a URL pointing to a player for a specific video.

Sources

1. Google Search Central, "Video (VideoObject, Clip, BroadcastEvent) structured data", updated 24 September 2026
2. Schema.org, "VideoObject", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer