# Import recipes

> Read the schema.org JSON-LD that recipe sites publish into a recipe, check what was left out, read regional decimals and units, store the result, and resolve its ingredient links.

Source: https://recipe-book.siraj.page/guides/import-recipes/

Import a recipe from another site's page, given its URL. Recipe sites publish their recipes as [schema.org Recipe](https://schema.org/Recipe) JSON-LD in a `<script type="application/ld+json">` tag, for search engines' recipe results. [`findRecipeJsonLd`](https://recipe-book.siraj.page/reference/core/schema-org.md#findrecipejsonld) finds that JSON-LD in the page's HTML, and [`fromJsonLd`](https://recipe-book.siraj.page/reference/core/schema-org.md#fromjsonld) reads it into a [`Recipe`](https://recipe-book.siraj.page/reference/core/types.md#recipe), the model [`parseRecipe`](https://recipe-book.siraj.page/reference/core/parsing.md#parserecipe) returns. Both come from `@recipe-book/core/schema-org`. In a React app, replace `@recipe-book/core` with `@recipe-book/react/core` in this page's imports, so `@recipe-book/core/schema-org` becomes `@recipe-book/react/core/schema-org`. `fromJsonLd` doesn't throw for bad data, though an error thrown by a getter or proxy in its input passes through, so branch on `success`:

```ts
import { findRecipeJsonLd, fromJsonLd } from '@recipe-book/core/schema-org'

export async function importRecipe(url: string) {
  const response = await fetch(url)

  if (!response.ok) {
    throw new Error(`Fetching ${url} failed with status ${response.status}.`)
  }

  const [node] = findRecipeJsonLd(await response.text())
  const result = fromJsonLd(node)

  if (!result.success) {
    throw result.error
  }

  return result.data
}
```

`fromJsonLd` keeps image URLs as the page wrote them, so a relative one, such as `/img/pancakes.jpg`, would point at your own site. In `importRecipe`, before it returns the recipe, resolve its `image` and each step's `image` against the address the page loaded from, with `new URL(image, response.url).href`. Use `response.url`, not `url`: `fetch` follows redirects, such as from a short link or from `http` to `https`, and a relative URL belongs to the page it ends at.

> **Note**
>
> Run the import on a server or in a script. In a browser, `fetch` can read another site's page only when that site allows it with CORS headers, which recipe pages rarely send.

## Find the recipe in a page

`findRecipeJsonLd` returns the Recipe nodes it finds in the page, in document order except that a node's `@graph` comes before its `mainEntity`, or `[]` when there are none. It finds a Recipe at the top level of the JSON-LD, in the arrays and `@graph`s that sites wrap recipes in, or as the `mainEntity` of a node there:

```ts
import { findRecipeJsonLd } from '@recipe-book/core/schema-org'

const html = `<!doctype html>
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@graph": [
      { "@type": "WebPage", "@id": "https://example.com/pancakes" },
      { "@type": "Recipe", "name": "Buttermilk pancakes" }
    ]
  }
</script>`

findRecipeJsonLd(html) // [{ '@type': 'Recipe', name: 'Buttermilk pancakes' }]
findRecipeJsonLd('<p>No recipe here.</p>') // []
```

When it finds several, pass each one to `fromJsonLd`. A roundup page that lists its recipes in an `ItemList`, and has no Recipe in the places above, gives the Recipes in the list. When the list's items only link to the recipes' own pages, fetch each page and find its recipe there.

`findRecipeJsonLd` reads only JSON-LD, and unlike a recipe scraper, Recipe Book doesn't scrape a recipe from the rest of the page. A page whose recipe is only in microdata's `itemprop` attributes, in RDFa, or in its text gives `[]`.

Paste a page's HTML source into the [playground](https://recipe-book.siraj.page/playground/) to see the recipes it gives and what `fromJsonLd` reads from each one.

## Check what was left out

`fromJsonLd` is forgiving, because you can't fix another site's markup. It leaves out a value the recipe can't hold and reports it as an issue with the severity `warning`, so the import still succeeds. The issue's `path` points into the JSON-LD, such as `['recipeYield', 2]`, so you can find the value in the page:

```ts {7-9}
import { fromJsonLd } from '@recipe-book/core/schema-org'

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  name: 'Buttermilk pancakes',
  image: 'data:image/png;base64,iVBORw0KGgo=',
  prepTime: 10,
  recipeYield: ['4', '12 pancakes', '1 batch'],
  recipeIngredient: ['1 &frac12; cups (190 g) all-purpose flour', '2 eggs'],
  recipeInstructions: ['Whisk the flour and eggs.', 'Cook on a hot griddle.'],
})

if (!result.success) {
  throw result.error
}

result.warnings.map((issue) => issue.path) // [['image'], ['recipeYield', 2], ['prepTime']]
result.warnings.map((issue) => issue.message) // ['Expected an http or https URL, or a relative one, received "data:…". It is ignored.', 'Only one yield is read, "12 pancakes", so this one is ignored.', 'Expected an ISO 8601 duration such as "PT30M", received 10. It is ignored.']
result.data.servings // { amount: 4 }
result.data.yield // { amount: 12, unit: 'pancake', plural: 'pancakes' }
result.data.ingredients[0]?.items[0]?.quantity // { amount: 1.5, unit: 'cup' }
```

[`fromJsonLd`](https://recipe-book.siraj.page/reference/core/schema-org.md#fromjsonld) lists which `recipeYield` text it reads as servings and which as the yield. A value the recipe can't hold is left out with an issue whose message ends "It is ignored.", such as [`invalid_url`](https://recipe-book.siraj.page/errors.md#issue-invalid_url) for the `data:` image or [`invalid_type`](https://recipe-book.siraj.page/errors.md#issue-invalid_type) for a `HowToSupply` in `recipeIngredient` whose `name` and `text` are blank. Another number of servings with a different amount, a second yield, or a second duration in a time's list, such as the second yield here, is an [`ignored_value`](https://recipe-book.siraj.page/errors.md#issue-ignored_value) issue whose message names the value kept and ends "so this one is ignored." A list of images keeps one URL, as [`image`](https://recipe-book.siraj.page/reference/core/schema-org.md#fields-it-reads) describes. A list in another field that holds one value, such as two descriptions, is a value the recipe can't hold. [Issue codes](https://recipe-book.siraj.page/errors.md#issue-codes) lists every code.

`fromJsonLd` strips comments, tags, and the content of `script` and `style` elements as it reads, then decodes HTML entities, so the flour's `&frac12;` is ½. To hold back an import with any issue, such as in a content pipeline, check `result.warnings.length` too.

## Handle a failed import

The import fails only when there's no Recipe node, or the recipe's name is missing, isn't text, or is only whitespace once its markup is removed and its entities decoded, such as `''`, `'<p>&nbsp;</p>'`, or `'<style>p {}</style>'`. `result.error` is a [`RecipeValidationError`](https://recipe-book.siraj.page/reference/core/errors.md#recipevalidationerror), and its `issues` include the warnings, so you see everything wrong with the page at once:

```ts
import { fromJsonLd } from '@recipe-book/core/schema-org'

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  recipeIngredient: ['2 eggs'],
})

if (!result.success) {
  result.error.issues.map((issue) => issue.message) // ['Add a name for the recipe.', 'Recipe has no steps.']
}

const empty = fromJsonLd(undefined)

if (!empty.success) {
  empty.error.issues.map((issue) => issue.message) // ['Expected a schema.org Recipe, or an array, @graph, mainEntity, or ItemList that holds one, received undefined.']
}
```

The second import is what `importRecipe` gets for a page without a recipe. `result.error.message` lists the first 10 issues with their paths, one per line, so throwing the error gives a readable failure.

## Read regional pages

For a page that writes decimals with a comma, such as `'1,500 kg Mehl'` on a German page, pass `decimal: ','` to `fromJsonLd`, and for an Australian page's 250 mL cups and 20 mL tablespoons, pass `units`:

```ts {11}
import { fromJsonLd, toJsonLd } from '@recipe-book/core/schema-org'

const result = fromJsonLd(
  {
    '@context': 'https://schema.org',
    '@type': 'Recipe',
    name: 'Anzac biscuits',
    recipeIngredient: ['1 cup rolled oats', '2 tbsp golden syrup'],
    recipeInstructions: ['Mix, then bake.'],
  },
  { units: { cup: 'cup-metric', tbsp: 'tbsp-au' } },
)

if (!result.success) {
  throw result.error
}

result.data.ingredients[0]?.items.map((item) => item.quantity) // [{ amount: 1, unit: 'cup-metric' }, { amount: 2, unit: 'tbsp-au' }]
toJsonLd(result.data).data.recipeIngredient // ['1 cup rolled oats', '2 tbsp golden syrup']
```

`decimal` and `units` are the options [Read regional recipes](https://recipe-book.siraj.page/guides/author-recipes.md#read-regional-recipes) passes to `parseRecipe`. The page's `inLanguage` and the site's language don't set either option, because few pages declare a language and a language doesn't settle the decimal mark or the cup. Choose them for each site you import from. [`toJsonLd`](https://recipe-book.siraj.page/reference/core/schema-org.md#tojsonld) writes the recipe back as "1 cup rolled oats", or as "1 cup (250 mL) rolled oats" with `system: 'us'`, so a page you export reads back as metric cups only with the same `units`.

## Store the recipe

`result.data` is a recipe like any other, so you can [scale](https://recipe-book.siraj.page/guides/scale-a-recipe.md), [convert](https://recipe-book.siraj.page/guides/convert-units.md), and [render](https://recipe-book.siraj.page/guides/render-a-recipe-in-react.md) it. It's plain JSON data, so you can store it in a database. When you load it back, validate it with `parseRecipe`, which accepts any recipe that `parseRecipe` or `fromJsonLd` returned and returns an equal recipe:

```ts {17-18}
import { parseRecipe } from '@recipe-book/core'
import { fromJsonLd } from '@recipe-book/core/schema-org'

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  name: 'Buttermilk pancakes',
  author: { '@type': 'Person', name: 'Ada' },
  recipeIngredient: ['1 ½ cups (190 g) all-purpose flour', '2 eggs'],
  recipeInstructions: ['Whisk the flour and eggs.', 'Cook on a hot griddle.'],
})

if (!result.success) {
  throw result.error
}

const saved = JSON.stringify(result.data)
const loaded = parseRecipe(JSON.parse(saved))

loaded.success && JSON.stringify(loaded.data) === saved // true
result.extra // { author: { '@type': 'Person', name: 'Ada' } }
```

`result.extra` holds the node's fields that the recipe doesn't model, such as `author` and `keywords`, as the page wrote them, but not its `@context` or `@type`. Store it alongside the recipe to credit the source. When the page gives `author` as an `@id` reference to a `Person` elsewhere in its JSON-LD, as Yoast and WP Recipe Maker pages do, `findRecipeJsonLd` puts that `Person` in its place, so `extra.author` holds the author's `name`. `fromJsonLd` keeps the reference when you pass it the page's parsed JSON instead.

Before you publish the recipe with your own JSON-LD, through [`toJsonLd`](https://recipe-book.siraj.page/reference/core/schema-org.md#tojsonld) or [`<Recipe.JsonLd>`](https://recipe-book.siraj.page/reference/react/json-ld.md), take the source page's fields out of `extra`: `@id`, `url`, `mainEntityOfPage`, and `isPartOf` identify the other site's page, and `aggregateRating` and `review` are the ratings its readers gave. `toJsonLd` writes every field in `extra` that it doesn't write from the recipe, so your page would claim them as its own.

## Resolve ingredient links

Some sites link an ingredient line to a product page or another recipe. The first http, https, or relative link in a line becomes the ingredient's `url`, and the line's text reads as it would without it:

```ts
import { fromJsonLd } from '@recipe-book/core/schema-org'

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  name: 'Sandwich bread',
  recipeIngredient: [
    '3 cups (360g) <a href="https://shop.example.com/flour">All-Purpose Flour</a>',
    '1 cup <a href="/recipes/sourdough-starter">sourdough starter</a>',
  ],
  recipeInstructions: ['Mix, knead, and bake.'],
})

result.success && result.data.ingredients[0]?.items[0] // { id: 'all-purpose-flour', name: 'All-Purpose Flour', quantity: { amount: 3, unit: 'cup' }, equivalents: [{ amount: 360, unit: 'g' }], url: 'https://shop.example.com/flour', optional: false }
result.success && result.data.ingredients[0]?.items[1]?.url // '/recipes/sourdough-starter'
```

A link to a place on the same page (`#…`), or an empty one, is skipped without a warning, so a later link in the line can give the `url`.

Some relative links, such as `//host/path`, point to another site. `fromJsonLd` also keeps [a `HowToTool`'s `url`](https://recipe-book.siraj.page/reference/core/schema-org.md#fromjsonld) as written, in `equipment[].url`. When you import, before you store the recipe, resolve each ingredient's `url` and each `equipment[].url`, as you resolve the `image` and each step's `image` in `importRecipe`:

```ts
import type { Recipe } from '@recipe-book/core'
import { fromJsonLd } from '@recipe-book/core/schema-org'

function resolveUrl(url: string, page: string): string | undefined {
  return URL.canParse(url, page) ? new URL(url, page).href : undefined
}

function resolveLinks(recipe: Recipe, page: string): Recipe {
  return {
    ...recipe,
    ingredients: recipe.ingredients.map((section) => ({
      ...section,
      items: section.items.map((ingredient) =>
        ingredient.url === undefined
          ? ingredient
          : { ...ingredient, url: resolveUrl(ingredient.url, page) },
      ),
    })),
    equipment: recipe.equipment.map((item) =>
      item.url === undefined
        ? item
        : { ...item, url: resolveUrl(item.url, page) },
    ),
  }
}

const result = fromJsonLd({
  '@context': 'https://schema.org',
  '@type': 'Recipe',
  name: 'Sandwich bread',
  recipeIngredient: [
    '1 cup <a href="/recipes/sourdough-starter">sourdough starter</a>',
    '3 cups <a href="//shop.example.com/flour">flour</a>',
  ],
  recipeInstructions: ['Mix, knead, and bake.'],
  tool: [{ '@type': 'HowToTool', name: 'loaf pan', url: '/shop/loaf-pan' }],
})

if (!result.success) {
  throw result.error
}

const recipe = resolveLinks(result.data, 'https://example.com/bread')
recipe.ingredients[0]?.items.map((ingredient) => ingredient.url) // ['https://example.com/recipes/sourdough-starter', 'https://shop.example.com/flour']
recipe.equipment.map((item) => item.url) // ['https://example.com/shop/loaf-pan']
```

To show no links instead, remove them with `items: section.items.map(({ url, ...ingredient }) => ingredient)`.

[`fromJsonLd`](https://recipe-book.siraj.page/reference/core/schema-org.md#fromjsonld) lists the links it leaves out and the issues they give. The link's text isn't kept apart from the line, and the link belongs to the whole ingredient, so the words of a "learn more" link can end up in the ingredient's name or note. To render the link, make the ingredient's name a link with [`asChild`](https://recipe-book.siraj.page/reference/react/ingredients.md#render-a-sub-part-as-your-own-element).

## Read a pasted recipe

Recipe Book has no reader for a whole recipe written as text, such as one pasted from a recipe card. [`parseRecipe`](https://recipe-book.siraj.page/reference/core/parsing.md#parserecipe) reads ingredient lines only when you pass it [`parseIngredientLine`](https://recipe-book.siraj.page/reference/core/parsing.md#parseingredientline), and then keeps each line and step as written, so a line such as `'For the glaze:'` would be an ingredient, and `'1. Heat the oven.'` would keep its number in a list that numbers its steps. `fromJsonLd` reads a recipe's lines by the rules recipe sites need, so split the text into its name, its ingredient lines, and its method, and pass them to `fromJsonLd` as a schema.org Recipe:

```ts
import { fromJsonLd } from '@recipe-book/core/schema-org'

function readPastedRecipe(text: string) {
  const [name = '', ...lines] = text
    .split('\n')
    .map((line) => line.trim())
    .filter((line) => line !== '')
  const method = lines.findIndex((line) => /^method$/i.test(line))

  if (method === -1) {
    throw new Error('Write the steps after a line that says "Method".')
  }

  return fromJsonLd({
    '@type': 'Recipe',
    name,
    recipeIngredient: lines
      .slice(0, method)
      .filter((line) => !/^ingredients$/i.test(line)),
    recipeInstructions: lines.slice(method + 1).join('\n'),
  })
}

const result = readPastedRecipe(`Lemon drizzle cake

Ingredients
1 cup (200 g) sugar
1 ½ cups (190 g) self-rising flour
2 eggs
For the glaze:
1 cup (120 g) powdered sugar
2 tbsp lemon juice

Method
1. Heat the oven to 350°F.
2. Beat the sugar, flour, and eggs, then bake for 45 minutes.
Step 3
Whisk the glaze and pour it over the warm cake.`)

if (!result.success) {
  throw result.error
}

result.data.ingredients.map((section) => section.title) // [undefined, 'For the glaze']
result.data.ingredients[1]?.items.map((ingredient) => ingredient.name) // ['powdered sugar', 'lemon juice']
result.data.steps[0]?.items.map((step) => step.text) // ['Heat the oven to 350°F.', 'Beat the sugar, flour, and eggs, then bake for 45 minutes.', 'Whisk the glaze and pour it over the warm cake.']
result.warnings // []
```

`'For the glaze:'` titles a section of the lines after it, because it reads as a heading: it has a letter but no number, and it ends in a colon. A step's number of one or two digits followed by a period and a space, such as `'1. '`, is left out, but one written as `'1) '` stays in the step's text, and a line that's only a step's label, such as `'Step 3'`, isn't a step. [`fromJsonLd`](https://recipe-book.siraj.page/reference/core/schema-org.md#fromjsonld) lists every rule in its `recipeIngredient` and `recipeInstructions` rows and in the paragraphs on sections and on `recipeInstructions` text after its table.

`readPastedRecipe` removes the lines that say only "Ingredients" and "Method" before it calls `fromJsonLd`. With no colon, a bare "Ingredients" isn't a heading by those rules, so it would be an ingredient named "Ingredients", and "Method" would be a step, with no warning for either. Recipe cards differ in how they set out a name, servings, and the method, so adjust the split to the text your readers paste.

## Next steps

- [schema.org JSON-LD](https://recipe-book.siraj.page/reference/core/schema-org.md) for `findRecipeJsonLd`, `fromJsonLd`, and every field `fromJsonLd` reads
- [Issue codes](https://recipe-book.siraj.page/errors.md#issue-codes) for every issue code and its fix
- [Validate recipes](https://recipe-book.siraj.page/guides/validate-recipes.md) for recipe input from a CMS, an API, or a form
- [Render a recipe in React](https://recipe-book.siraj.page/guides/render-a-recipe-in-react.md) to show the recipe
- [`<Recipe.IngredientName>`](https://recipe-book.siraj.page/reference/react/ingredients.md#ingredientname) to render an ingredient's name as its link
