contentUrl

contentUrl · Recommended

Appears in

VideoObject

What is it?

contentUrl is the direct URL to a video's actual file bytes. Unlike embedUrl, which points to a player, contentUrl links to the raw media file itself (e.g., an .mp4 or .webm file). Search engines use it to verify that real video content exists at the specified location.

Why this matters for AEO

When an AI engine processes a video result, contentUrl provides a direct reference to the actual video file. This allows AI systems to verify the video exists and potentially analyze its metadata (file type, duration, codec). For queries like "download tutorial on React hooks," AI engines that reference contentUrl can distinguish between pages that host actual video files and pages that only embed third-party players.

What the specs say

Schema.org: URL. Actual bytes of the media object, for example the image file or video file. schema.org/contentUrl

Google: Recommended. "A URL pointing to the video file's actual content bytes, in one of the supported file types. Don't link to the page where the video lives; this must be the URL of the video file's actual content bytes itself." Google Video Structured Data

Google requires either contentUrl or embedUrl (or both) for video rich results.

How to find your value

• Self-hosted — The direct URL to your .mp4, .webm, or .ogg file on your server or CDN
• YouTube — https://www.youtube.com/v/VIDEO_ID (player URL format, not direct file)
• Vimeo — Not publicly exposed; use embedUrl instead
• Wistia — Wistia API provides direct file URLs for paid accounts
• Cloud storage — The public URL of the video file in S3, GCS, or Azure Blob Storage

Most video hosting platforms do not expose direct file URLs. If you use YouTube, Vimeo, or similar platforms, provide embedUrl instead.

Format and code

Expected type: URL (string)

The URL must point to the video file itself, not a page or player.

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "Product Demo: Schema HQ",
  "contentUrl": "https://cdn.example.com/videos/schema-hq-demo.mp4",
  "thumbnailUrl": "https://cdn.example.com/images/schema-hq-demo-thumb.jpg",
  "uploadDate": "2024-05-20T09:00:00Z",
  "description": "Watch how Schema HQ generates and publishes structured data for Webflow sites"
}

Using both contentUrl and embedUrl:

{
  "@type": "VideoObject",
  "name": "Product Demo: Schema HQ",
  "contentUrl": "https://cdn.example.com/videos/schema-hq-demo.mp4",
  "embedUrl": "https://www.youtube.com/embed/abc123"
}

Invalid: A page URL (https://example.com/videos/demo) or a player URL (https://youtube.com/embed/abc123). Those belong in url and embedUrl respectively.

Webflow implementation

Static pages

In Page Settings > Custom Code > Head Code, set contentUrl to the direct file URL of your self-hosted video. If you use a video hosting platform that does not expose file URLs, use embedUrl instead.

CMS template pages

Create a Plain Text CMS field for the video file URL. Only populate it when you have a direct file link:

"contentUrl": "{{wf {"path":"video-file-url","type":"PlainText"} }}"

In Schema HQ

The contentUrl field detects whether a video has a direct file URL or an embed-based player. It maps contentUrl when a direct file is available and falls back to embedUrl for third-party embeds, ensuring at least one is always present.

Real examples

Hotstar provides both contentUrl and embedUrl:

{
  "@type": "VideoObject",
  "name": "Super 4s: PAK vs IND",
  "contentUrl": "https://www.hotstar.com/stream/super-4s-pakistan-vs-india",
  "embedUrl": "https://www.hotstar.com/in/sports/cricket/super-4s-pakistan-vs-india/1540025325"
}

Source: hotstar.com

Most video platforms (YouTube, Vimeo, TED) do not include contentUrl in their VideoObject markup because they do not expose direct file URLs publicly.

Related fields

• embedUrl · URL of the video player (alternative to contentUrl)
• thumbnailUrl · Preview image for the video
• encodingFormat · MIME type of the video file (e.g., video/mp4)
• uploadDate · When the video was first published
• duration · Length of the video

FAQ

Do I need both contentUrl and embedUrl?

No. Google requires at least one of them. If you self-host video files, provide contentUrl. If you embed videos from YouTube, Vimeo, or similar platforms, provide embedUrl. Providing both gives Google the most information.

Why is contentUrl rare in practice?

Most websites embed videos from platforms like YouTube and Vimeo, which do not expose direct file URLs. contentUrl is primarily used by sites that self-host their video files or by platforms like Hotstar that serve their own streams.

Can contentUrl point to a streaming manifest (HLS/DASH)?

Google's documentation references "actual content bytes" in supported file types. Standard video files (.mp4, .webm) are safest. Streaming manifest URLs (.m3u8, .mpd) may not be recognized by all consumers. If using adaptive streaming, provide embedUrl as the primary field.