Using the SharePoint Online EmbedService API to Fetch the Title, Thumbnail Image, and More for Any URL

Web Design & Development

In my current SharePoint Online intranet project, one of the requirements is to have a web part similar to the five-tile grid “Hero” web part that displays a comment count (if linking to a modern news page) in addition to the title text. For the web part, I wanted to make it as easy as possible for users to enter a URL and then auto-populate all relevant fields for each tile in the web part. Fortunately there is an API endpoint that the Quick Links and Link web parts use that I can leverage.

I thought it was convenient that the Link and Quick Links web parts would auto-populate the title, image, and description fields after you enter a URL. After some searching online I was a bit surprised that I did not find any obvious documentation or tutorials/blogs about this feature. So I opened my browser dev tools and watched the network requests as I entered a URL into a Link web part. Sure enough, an XHR/fetch request to a SharePoint API endpoint returned the data that the web part used to populate the image, title, and description.

Screenshot of Firefox dev tools showing the response from the SP.Publishing.EmbedService API call
I was able to see how the Links web part fetched data about the URL I entered using the Network tab of my browser developer tools (Firefox in this screenshot).

The endpoint is /_api/SP.Publishing.EmbedService/EmbedData?url='[url]'&version=1 where the [url] is replaced with the URL to the page you want to retrieve data from. It looks like it uses some internal querying if you use a URL in your SharePoint tenant, because it returns not only the typical open graph data like title, image, description, but also CreatorName with data about the SharePoint user and WebId, SiteId, ListId, and UniqueId. These actually came in very handy because I needed to make some additional REST calls to determine if the URL was in fact a news article with comments. Also note that the ThumbnailUrl uses the getpreview.ashx service to return an optimized version of the image from SharePoint Online. Here is an example of the data returned for a call to an internal SharePoint URL (https://yourtenant.sharepoint.com/sites/yoursite/_api/SP.Publishing.EmbedService/EmbedData?url=’https://yourtenant.sharepoint.com/sites/yoursite/SitePages/Communication%20Site%20Templates%20Enable%20News%20Posts.aspx’&version=1):

{
  "@odata.context": "https://yourtenant.sharepoint.com/sites/yoursite/_api/$metadata#EmbedDataV1s/$entity",
  "@odata.type": "#SP.Publishing.EmbedDataV1",
  "@odata.id": "https://yourtenant.sharepoint.com/sites/yoursite/_api/SP.Publishing.EmbedService/EmbedData",
  "@odata.editLink": "SP.Publishing.EmbedService/EmbedData",
  "AllowHttpsEmbed": false,
  "CreatorName": "11;#Josh McCarty,#i:0#.f|membership|josh.mccarty@yourtenant.com,#josh.mccarty@yourtenant.com,#josh.mccarty@yourtenant.com,#Josh McCarty",
  "DatePublishedAt": "2017-10-26T08:09:19.0000000",
  "Description": "These new site templates also have new web parts that are responsively designed to work on any screen size.",
  "EmbedServiceResponseCode": 0,
  "ErrorMessage": null,
  "Html": "<iframe width='100%' height='70%' src='https://yourtenant.sharepoint.com/sites/yoursite/SitePages/Communication%2520Site%2520Templates%2520Enable%2520News%2520Posts.aspx' allowfullscreen></iframe>",
  "ListId": "4b649c15-79dd-4c93-9826-824759da51e3",
  "PublisherName": "",
  "ResponseCode": 0,
  "SiteId": "0a5fbe4a-1c6b-4cc7-b061-bc7c7285c464",
  "ThumbnailUrl": "https://yourtenant.sharepoint.com:443/sites/yoursite/_layouts/15/getpreview.ashx?guidFile=47e8ace6%2Daaa4%2D432b%2D9517%2D80d301142e33&guidWeb=208e5d9f%2Db154%2D4ad2%2D932a%2De79c8a82e908&guidSite=0a5fbe4a%2D1c6b%2D4cc7%2Db061%2Dbc7c7285c464",
  "Title": "Communication Site Templates Enable News Posts",
  "Type": "rich",
  "UniqueId": "47e8ace6-aaa4-432b-9517-80d301142e33",
  "Url": "https://yourtenant.sharepoint.com/sites/yoursite/SitePages/Communication%20Site%20Templates%20Enable%20News%20Posts.aspx",
  "VideoId": null,
  "WebId": "208e5d9f-b154-4ad2-932a-e79c8a82e908"
}

For external URLs, SharePoint appears to proxy the request to the Bing Preview API. Here is an example of the data returned from a recent post on my website (https://yourtenant.sharepoint.com/sites/yoursite/_api/SP.Publishing.EmbedService/EmbedData?url=’https://joshmccarty.com/made-tool-generate-images-using-office-ui-fabric-icons/’&version=1):

{
  "@odata.context": "https://yourtenant.sharepoint.com/sites/yoursite/_api/$metadata#EmbedDataV1s/$entity",
  "@odata.type": "#SP.Publishing.EmbedDataV1",
  "@odata.id": "https://yourtenant.sharepoint.com/sites/yoursite/_api/SP.Publishing.EmbedService/EmbedData",
  "@odata.editLink": "SP.Publishing.EmbedService/EmbedData",
  "AllowHttpsEmbed": false,
  "CreatorName": "",
  "DatePublishedAt": "",
  "Description": "I've been working on a new intranet project that uses modern communication sites in SharePoint Online, and we're using the new Quick Links web part in two",
  "EmbedServiceResponseCode": 200,
  "ErrorMessage": null,
  "Html": "",
  "ListId": "",
  "PublisherName": "",
  "ResponseCode": 0,
  "SiteId": "",
  "ThumbnailUrl": "https://dyukvup4sm4dk.cloudfront.net/wp-content/uploads/2017/12/office-ui-fabric-icon-images.png",
  "Title": "I Made a Tool to Generate Images Using Office UI Fabric ...",
  "Type": "rich",
  "UniqueId": "",
  "Url": "https://joshmccarty.com/made-tool-generate-images-using-office-ui-fabric-icons/",
  "VideoId": null,
  "WebId": ""
}

I found out external requests use the Bing Preview API because when I tried a bogus URL this was the response:

{
  "@odata.context": "https://yourtenant.sharepoint.com/sites/yoursite/_api/$metadata#EmbedDataV1s/$entity",
  "@odata.type": "#SP.Publishing.EmbedDataV1",
  "@odata.id": "https://yourtenant.sharepoint.com/sites/yoursite/_api/SP.Publishing.EmbedService/EmbedData",
  "@odata.editLink": "SP.Publishing.EmbedService/EmbedData",
  "AllowHttpsEmbed": false,
  "CreatorName": "",
  "DatePublishedAt": "",
  "Description": "",
  "EmbedServiceResponseCode": 200,
  "ErrorMessage": "Bing Preview API return empty data or error data.",
  "Html": "",
  "ListId": "",
  "PublisherName": "",
  "ResponseCode": 3,
  "SiteId": "",
  "ThumbnailUrl": "",
  "Title": "",
  "Type": "rich",
  "UniqueId": "",
  "Url": "http://fakewebsite",
  "VideoId": null,
  "WebId": ""
}

It also works nicely for YouTube videos (and I presume many other services that offer oEmbed or similar functionality) by returning the VideoID and the iframe embed code in the Html property:

{
  "@odata.context": "https://yourtenant.sharepoint.com/sites/yoursite/_api/$metadata#EmbedDataV1s/$entity",
  "@odata.type": "#SP.Publishing.EmbedDataV1",
  "@odata.id": "https://yourtenant.sharepoint.com/sites/yoursite/_api/SP.Publishing.EmbedService/EmbedData",
  "@odata.editLink": "SP.Publishing.EmbedService/EmbedData",
  "AllowHttpsEmbed": true,
  "CreatorName": "Microsoft Ignite",
  "DatePublishedAt": "2016-09-29T03:38:57.0000000",
  "Description": "In this session, learn how to manage your Microsoft SharePoint Online (SPO) and Microsoft OneDrive for Business environments in the browser (the SharePoint Online ...",
  "EmbedServiceResponseCode": 200,
  "ErrorMessage": null,
  "Html": "<iframe width=\"1280\" height=\"720\" src=\"https&#58;//www.youtube.com/embed/FaRy3I9P6E4?autoplay=0\" frameborder=\"0\" allowfullscreen=\"\"></iframe>",
  "ListId": "",
  "PublisherName": "YouTube",
  "ResponseCode": 0,
  "SiteId": "",
  "ThumbnailUrl": "https://www.bing.com/th?id=OVP.hGV1bS9uCTeLh8v1f88Q7wEsCo&pid=Api",
  "Title": "Learn best practices for managing and administering SharePoint Online and OneDrive for Business",
  "Type": "video",
  "UniqueId": "",
  "Url": "https://www.youtube.com/watch?v=FaRy3I9P6E4",
  "VideoId": "0F99BFC84706882501540F99BFC8470688250154",
  "WebId": ""
}

I’m a little concerned that this API may change or stop working in the future because I can’t seem to find any documentation on it. However the version parameter could mean that if changes are necessary they’ll just increment that number and keep the existing version in-place (I hope). The custom web part I’m creating still allows manual entry of all data–in case the API call fails for some reason or if the user simply wants to tweak the title or change the image. Regardless, this is exactly the kind of additional capability you would expect out of an evolving service like Office 365, and I’m very impressed with it so far. If anyone knows more about this API or has a link to official documentation, please let me know in the comment section!


Comments

  1. Love this. Bookmarked your post. Thanks for posting. I can see this API being used allot to provide richer interfaces. I wonder if it is the same one that the modern document libraries use to display file thumbnails? ?
  2. Great Post. I was stuck in fetching the thumbnail URL from Sharepoint Online for weeks. Your Post saved me from extra days of struggle. It's working perfect for Images and PDF thumbnails, but I'm facing "HTTP 501" error when i try for text file thumbnails. Can you please help me out in fixing this issue?
    1. Sorry, I'm not sure how to retrieve the thumbnail image for a text file. I'm getting the same error as you when I try. Looking at how a modern document library loads text file thumbnails, it appears to use another separate service (https://eastus1-mediap.svc.ms/transform/thumbnail?... instead of getpreview.ashx) with several query string parameters to generate/retrieve the thumbnail image. Maybe you can reverse-engineer how that works or find some documentation on it? Good luck!
  3. If someone has a solution how to generate preview from txt file? For example how use mediap.svc.ms/transform/thumbnail?

Comments are closed