POST /web_json_ld • Credits: 1 credit per call

JSON-LD Extractor reads every JSON-LD block from one public web page and returns the parsed objects. The response holds an items array of schema.org objects, a count of the objects found, and the run time of the call. Each call costs 1 credit.

What does JSON-LD Extractor do?

JSON-LD is a block of JSON that a website puts inside its own HTML to describe the page in machine-readable form. A publisher adds it so that Google, Bing and answer engines read the price, the rating, the author or the address without a guess. JSON-LD Extractor solves the collection problem. The endpoint fetches the page, finds every <script type="application/ld+json"> tag, and parses the JSON inside each one. One tag can hold a single object or an array of objects, and the endpoint returns each object as a separate entry in items. JSON-LD Extractor is a member of the RichAPI web scraper family.

Which schema.org types does JSON-LD Extractor return?

JSON-LD Extractor returns every schema.org type that the page carries. It applies no filter and no allowed list. The @type key on each item names the type. These four types cover most commercial pages.

`@type`	Where the type appears	Typical keys
`Organization`	A company home page or an about page.	`name`, `url`, `logo`, `sameAs`
`Product`	An ecommerce product page.	`name`, `sku`, `brand`, `offers`, `aggregateRating`
`Article`	A news story or a blog post.	`headline`, `author`, `datePublished`, `image`
`LocalBusiness`	A store page or a location page.	`name`, `address`, `telephone`, `openingHours`

A page often carries several blocks at once. A product page carries Product, Organization and BreadcrumbList together.

Why is JSON-LD the highest-quality structured data on a page?

The site owner writes the JSON-LD block on purpose, for machines to read. The block arrives typed, explicit and already valid JSON, so no HTML parse step and no guess step stands between the page and the value. A meta tag holds one line of free text. A JSON-LD block holds a full object, with a price, a currency, a stock state, a rating count or a postal address. Scraped page text holds the same facts, but it mixes them with layout and marketing copy. For that reason, JSON-LD is the highest-quality structured data that a public page offers.

Which endpoint does JSON-LD Extractor use?

Method:POST
URL:https://api.richapi.ai/api/v1/web_json_ld
Authentication:x-api-key header
Response: Synchronous JSON
Credits: 1 credit per call

How to send a JSON-LD Extractor request

Copy your API key from the RichAPI dashboard.
Set the url parameter to the full page URL.
To accept a stored copy of the page data, set cache to true.
Send a POST request to https://api.richapi.ai/api/v1/web_json_ld.
Send the API key in the x-api-key header.
Read the data.items array from the response.

CAUTION: Each JSON-LD Extractor call costs 1 credit. A page with no JSON-LD returns status 200 and still costs 1 credit.

cURL

curl -X POST https://api.richapi.ai/api/v1/web_json_ld   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "url": "https://www.bbc.com/news",
    "cache": true
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/web_json_ld",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "url": "https://www.bbc.com/news",
        "cache": True,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

for item in data["data"]["items"]:
    print(item.get("@type"))

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/web_json_ld", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.bbc.com/news",
    cache: true,
  }),
});

const data = await response.json();
console.log(data.data.items.map((item) => item["@type"]));

Which parameters does JSON-LD Extractor accept?

Parameter	Type	Required	Default	Description
`url`	string	Yes	None	The full HTTP or HTTPS URL of the page to read. The maximum length is 2048 characters.
`cache`	boolean	No	`false`	Set to `true` to accept a stored copy of the page data from the last 6 hours.

What does JSON-LD Extractor return?

The block below is an example response for a news home page. The values are illustrative. Each entry in data.items keeps the exact keys that the page author wrote, so the shape of an item follows schema.org and not RichAPI.

{
  "data": {
    "items": [
      {
        "@context": "https://schema.org",
        "@type": "Organization",
        "name": "BBC News",
        "url": "https://www.bbc.com/news",
        "logo": {
          "@type": "ImageObject",
          "url": "https://static.bbc.co.uk/news/1.0/img/bbc-news-logo.png",
          "width": 600,
          "height": 60
        },
        "sameAs": [
          "https://www.facebook.com/bbcnews",
          "https://twitter.com/BBCNews",
          "https://www.youtube.com/bbcnews"
        ]
      },
      {
        "@context": "https://schema.org",
        "@type": "WebSite",
        "name": "BBC News",
        "url": "https://www.bbc.com/news",
        "publisher": {
          "@type": "Organization",
          "name": "BBC"
        }
      },
      {
        "@context": "https://schema.org",
        "@type": "NewsArticle",
        "headline": "Global chip demand climbs for a fourth quarter",
        "url": "https://www.bbc.com/news/articles/c8x71p3q9v4o",
        "datePublished": "2026-08-09T07:14:00+00:00",
        "dateModified": "2026-08-09T09:02:00+00:00",
        "author": {
          "@type": "Person",
          "name": "Amara Nwosu"
        },
        "publisher": {
          "@type": "Organization",
          "name": "BBC News",
          "logo": {
            "@type": "ImageObject",
            "url": "https://static.bbc.co.uk/news/1.0/img/bbc-news-logo.png"
          }
        },
        "image": [
          "https://ichef.bbci.co.uk/news/1024/branded_news/chip-demand.jpg"
        ],
        "articleSection": "Business"
      }
    ],
    "count": 3
  },
  "meta": {
    "cache_hit": false,
    "execution_time_ms": 412,
    "quality_warning": null
  }
}

Which fields does the JSON-LD Extractor response hold?

Field	Type	Description
`data.items`	array of objects	Every JSON-LD object found on the page. Each object keeps its original schema.org keys, such as `@context` and `@type`.
`data.count`	integer	The number of JSON-LD objects in `data.items`.
`meta.cache_hit`	boolean	The value is `true` for a response from the stored copy. The value is `false` for a response from the live page.
`meta.execution_time_ms`	integer	The run time of the call, in milliseconds.
`meta.quality_warning`	string or null	A warning about the extracted data. The value is `null` for a result with no warning.

What does JSON-LD Extractor return for a page with no JSON-LD?

Many pages carry no JSON-LD at all. JSON-LD Extractor treats that page as a success, not as a failure. The response returns status 200, an empty items array and a count of 0.

{
  "data": {
    "items": [],
    "count": 0
  },
  "meta": {
    "cache_hit": false,
    "execution_time_ms": 287,
    "quality_warning": null
  }
}

JSON-LD Extractor also skips a block that holds broken JSON. A page with one broken block and no other block returns the same empty result.

CAUTION: An empty result costs 1 credit. Check data.count before you store the result.

How much does JSON-LD Extractor cost?

JSON-LD Extractor costs 1 credit per call. 1 credit costs $0.02 on the 1,000 and 5,000 credit packs. Larger packs cost less per credit. The credit count does not change with the number of JSON-LD blocks on the page.

Calls	Credits	Cost
1	1	$0.02
100	100	$2.00
1,000	1,000	$20.00
10,000	10,000	$200.00

Which errors can JSON-LD Extractor return?

Status	Meaning	What to do
`400`	The request body failed validation.	Correct the parameter that the message names. Send a full HTTP or HTTPS URL.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	The organization has no credits left, or the team reached its monthly spend limit.	Buy credits in the RichAPI dashboard.
`403`	`Endpoint not available on your plan`: this API key has no access to this endpoint.	Call `GET /api/v1/my-endpoints` to list the endpoints this key can use. For access, write to [email protected].
`404`	The endpoint name is wrong.	Send the request to `/web_json_ld`.
`405`	The request used a method other than `POST`.	Send the request again with the `POST` method.
`422`	The service could not process a value, for example a URL that does not start with `http://` or `https://`, a URL longer than 2048 characters, or a private network address.	Send a full public HTTP or HTTPS URL.
`429`	Too many requests.	Read the `Retry-After` header. Wait that many seconds, then send the request again.
`500`	The API failed.	Send the request again. If the failure repeats, write to [email protected].
`502`	The target page returned an error, or the upstream service failed.	Confirm that the URL opens in a browser. Then send the request again.
`504`	The target page took too long.	Send the request again.

RichAPI charges no credit for a 400, 401, 402, 403, 404, 405, 422, 429, 500, 502 or 504 response.

Frequently asked questions

What is JSON-LD?

JSON-LD is a block of JSON inside a web page that describes the page in machine-readable form. The site owner adds it so that search engines and answer engines read facts such as a price, a rating, an author or an address.

Does JSON-LD Extractor render JavaScript?

JSON-LD Extractor fetches the raw HTML first, because most sites put the JSON-LD block straight in the HTML. If the page returns a thin JavaScript shell, the endpoint loads the page in a real browser and reads the rendered HTML instead.

Does a page with no JSON-LD cost a credit?

Yes. A page with no JSON-LD returns status 200 with an empty items array, and that call costs 1 credit. A 4xx or 5xx error costs no credit.

Why is count different from the number of script tags on the page?

One <script type="application/ld+json"> tag can hold an array of objects, and JSON-LD Extractor counts each object separately. The endpoint also skips a tag that holds broken JSON, which lowers the count.

What is the difference between JSON-LD Extractor and Meta Tags Extractor?

JSON-LD Extractor returns full schema.org objects, such as a product with a price and a rating. Meta Tags Extractor returns the OpenGraph, Twitter Card and SEO tags, which hold one line of text each.

How long does JSON-LD Extractor cache a page?

JSON-LD Extractor stores the extracted data for 6 hours. The cache parameter is false by default, so every call reads the live page until you set cache to true.

Can JSON-LD Extractor read a page behind a login?

No. JSON-LD Extractor accepts no login credentials and no cookies. It reads only a page that a public visitor can open, and it rejects a URL that points to a private network address.

JSON-LD Extractor API