Enrich captured content with the OneNote API

Learn how you can use the OneNote API to augment and transform content for a business card, online recipe, or online product listing.

Applies to: OneNote service

In this article
Business card extractions
Recipe extractions
Product listing extractions
Unknown content type extractions
Permission scopes
Response information

Your app or device can use the OneNote API to render enriched pages for the following captured content:

  • Contact information based on an image of a business card

  • Recipe picture, ingredients, and other information based on its URL

  • Product picture, rating, and other information based on its listing URL

You can use the enrichment API when you create a page. Simply include a div element that specifies the enrichment method, source content, and fallback behavior in your create-page request:

HTML
Copy 
<div
    data-render-src="image-or-url"
    data-render-method="enrichment-method"
    data-render-fallback="fallback-action">
</div>

The API renders enriched content for the source on a OneNote page in an easy-to-read format. If the API can't render enriched content, it performs the specified fallback action.

To use the enrichment features, the input div must contain the following attributes:

Attribute

Description

data-render-method

Required

The extraction method to run:

  • extract.businesscard

  • extract.recipe

  • extract.product

  • extract

For best results, specify the content type (business card, recipe, or product) if you know it. If the type is unknown, you can use the extract method and the OneNote API will try to auto-detect the type.

data-render-src

Required

The content source. Can be an image of a business card or an absolute URL from many popular recipe or product websites. In the create-page request, the value is sent as a named part in a multipart request or as a URL.

For best results when sending a URL, use the canonical URL defined in the HTML of the source webpage, if one is defined. Example: <link rel="canonical" href="www.domainname.com/page/123/size12/type987" />.

data-render-fallback

Defaults to render if omitted

The fallback behavior if the extraction fails:

  • render

Renders the source image or a snapshot of the recipe or product webpage.

  • none

Does nothing. This option is useful if you want to always include a snapshot of the business card or webpage on the page in addition to any extracted content. Be sure to send a separate img element in the request, as shown in the examples.

NoteNote

Stay tuned for new enrichment features as we update and expand our feature set. Check out the OneNote Developer Blog for the latest news.

The OneNote API tries to find and render the following contact information based on an image of a person's or company's business card.

  • Name

  • Title

  • Organization

  • Phone and fax numbers

  • Mailing and physical addresses

  • Email addresses

  • Websites

 Screenshot of contact information extracted for a business card.

A vCard (.VCF file) with the extracted contact information is also embedded in the page. The vCard is a convenient way to get the contact information when retrieving page HTML content.

Note Note

Business card extraction currently works best with English-language cards, but look for additional language support in the future.

Common scenarios

Extract business card information, and also render the business card image
Specify the extract.businesscard method and the none fallback. Also send an img element with the src attribute that also specifies the image. If the API is unable to extract any content, it renders the business card image only.

HTML
Copy 
<div
    data-render-src="name:scanned-card-image"
    data-render-method="extract.businesscard"
    data-render-fallback="none">
</div>
<img src="name:scanned-card-image" />

Extract business card information, and render the business card image only if the extraction fails
Specify the extract.businesscard method and use the default render fallback. If the API is unable to extract any content, it renders the business card image instead.

HTML
Copy 
<div
    data-render-src="name:scanned-card-image"
    data-render-method="extract.businesscard">
</div>

See Capture photos and images for examples that show how to send an image in a create-page request.

The OneNote API tries to find and render the following information based on a recipe's URL.

  • Hero image

  • Rating

  • Ingredients

  • Instructions

  • Prep, cook, and total times

  • Servings

 Screenshot of an extracted recipe.

The API is optimized for recipes from many popular sites such as Allrecipes.com, FoodNetwork.com, and SeriousEats.com.

Common scenarios

Extract recipe information, and also render a snapshot of the recipe webpage
Specify the extract.recipe method and the none fallback. Also send an img element with the data-render-src attribute set to the recipe URL. If the API is unable to extract any content, it renders a snapshot of the recipe webpage only.

This scenario potentially provides the most information because the webpage may include additional information, such as customer reviews and suggestions.

HTML
Copy 
<div
    data-render-src="http://allrecipes.com/recipe/guacamole/"
    data-render-method="extract.recipe"
    data-render-fallback="none">
</div>
<img data-render-src="http://allrecipes.com/recipe/guacamole/" />

Extract recipe information, and render a snapshot of the recipe webpage only if the extraction fails
Specify the extract.recipe method and use the default render fallback. If the API is unable to extract any content, it renders a snapshot of the recipe webpage instead.

HTML
Copy 
<div
    data-render-src="http://www.foodnetwork.com/recipes/alton-brown/creme-brulee-recipe.html"
    data-render-method="extract.recipe">
</div>

Extract recipe information, and also render a link to the recipe
Specify the extract.recipe method and the none fallback. Also send an a element with the src attribute set to the recipe URL (or you can send any other information you want to add to the page). If the API is unable to extract any content, only the recipe link is rendered.

HTML
Copy 
<div
    data-render-src="http://www.seriouseats.com/recipes/2014/09/diy-spicy-kimchi-beef-instant-noodles-recipe.html"
    data-render-method="extract.recipe"
    data-render-fallback="none">
</div>
<a href="http://www.seriouseats.com/recipes/2014/09/diy-spicy-kimchi-beef-instant-noodles-recipe.html">Recipe URL</a>

The OneNote API tries to find and render the following information based on a product URL.

  • Title

  • Rating

  • Primary image

  • Description

  • Features

  • Specifications

 Screenshot of an extracted product listing.

The API is optimized for products from many popular sites such as Amazon.com, HomeDepot.com, and Sears.com.

Common scenarios

Extract product information, and also render a snapshot of the product webpage
Specify the extract.product method and the none fallback. Also send an img element with the data-render-src attribute set to the product URL. If the API is unable to extract any content, it renders a snapshot of the product webpage only.

This scenario potentially provides the most information because the webpage may include additional information, such as customer reviews and suggestions.

HTML
Copy 
<div
    data-render-src="http://www.amazon.com/Microsoft-Band-Small/dp/B00P2T2WVO"
    data-render-method="extract.product"
    data-render-fallback="none">
</div>
<img data-render-src="http://www.amazon.com/Microsoft-Band-Small/dp/B00P2T2WVO" />

Extract product information, and render a snapshot of the product webpage only if the extraction fails
Specify the extract.product method and use the default render fallback. If the API is unable to extract any content, it renders a snapshot of the product webpage instead.

HTML
Copy 
<div
    data-render-src="http://www.sears.com/craftsman-19hp-42-8221-turn-tight-174-hydrostatic-yard-tractor/p-07120381000P"
    data-render-method="extract.product">
</div>

Extract product information, and also render a link to the product
Specify the extract.product method and the none fallback. Also send an a element with the src attribute set to the product URL (or you can send any other information you want to add to the page). If the API is unable to extract any content, only the page link is rendered.

HTML
Copy 
<div
    data-render-src="http://www.homedepot.com/p/Active-Ventilation-5-Watt-Solar-Powered-Exhaust-Attic-Fan-RBSF-8-WT/204203001"
    data-render-method="extract.product"
    data-render-fallback="none">
</div>
<a href="http://www.homedepot.com/p/Active-Ventilation-5-Watt-Solar-Powered-Exhaust-Attic-Fan-RBSF-8-WT/204203001">Product URL</a>

If you don't know the content type (business card, recipe, or product) that you're sending, you can use the unqualified extract method and let the OneNote API automatically detect the type. You might want to do this if your app sends different capture types.

Tip Tip

If you know the content type that you're sending, you should use the extract.businesscard, extract.recipe, or extract.product method. In some cases, this can help to optimize the extraction results.

Send an image or a URL, and render the supplied image or a snapshot of the webpage if the extraction fails
Specify the extract method so the API automatically detects the content type, and use the default render fallback. If the API is unable to extract any content, it renders the supplied image or snapshot of the webpage instead.

HTML
Copy 
<div
    data-render-src="some image or url"
    data-render-method="extract">
</div>

To create page content, you’ll need to pass the following permission level when you authenticate the user:

  • office.onenote_create

See OneNote permission scopes for more information about permission scopes and how they work.

The OneNote API returns the following information in the response.

Response data

Description

Success code

A 201 HTTP status code for a successful POST request, and a 204 HTTP status code for a successful PATCH request.

Errors or warnings

If the extraction fails, the API processes as much of the request as possible and returns a 20136 warning code in the api.diagnostics property in the response body. The extraction will fail if:

  • The required data-render-src or data-render-method attributes are missing.

  • The data-render-src, data-render-method, or data-fallback-method values are empty or invalid.

Sometimes the API can extract only part of the target content even when it is available. In this case, the service processes as much of the request as possible but does not return a warning.

X-CorrelationId

An X-header with a GUID that uniquely identifies the request. The correlation ID can be used when debugging problems.
Show: