JSON-LD, microdata and Open Graph
schema.org is a shared vocabulary for describing things on the web: products, offers, articles, events and many more. Pages publish it in a few formats:
- JSON-LD: a
<script type="application/ld+json">block with a JSON object. It is separate from the visible markup, which makes it the easiest to read. - Microdata:
itemscope,itemtypeanditempropattributes spread across the HTML elements. - Open Graph:
og:*meta tags in the head, meant for link previews. They give a title, description, image and type, and shops sometimes add price tags.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Trail Running Shoe",
"sku": "TRS-42",
"offers": {
"@type": "Offer",
"price": "119.95",
"priceCurrency": "EUR",
"availability": "https://schema.org/InStock"
}
}
</script>Because this data feeds search results, sites keep it accurate and it changes less often than the page layout. A scraper that reads it survives redesigns that break CSS selectors.
The messy parts
Structured data is not always clean. Common problems:
- Several JSON-LD blocks on one page, or one block with an
@grapharray mixing the product with breadcrumbs and organisation data. - Variants described as a
ProductGroup, and price ranges as anAggregateOffer. - Prices written as local strings such as
1.299,00 €, where the period is a thousands separator and the comma the decimal point. - Availability as a full schema.org URL, a short name, or free text in the site's language.
Structured data can also disagree with the visible page. A shop may update the price shown to visitors and forget the JSON-LD, or mark a product as in stock in its markup while the page says it is sold out. If accuracy matters, spot-check a sample of pages against what a visitor sees, and keep the source of each value so you can trace a bad number back to the page it came from.
Each of these needs code, and the code needs maintenance as you add sites. That is the work the Siftzo Data API does for you.
Records from the Data API
GET /v1/data/{source} scrapes a page and returns a record with fixed fields. source is product, article or metadata.
curl "https://api.siftzo.com/v1/data/product?url=https://shop.example.com/p/trs-42" \
-H "X-API-Key: $SIFTZO_API_KEY"Siftzo reads JSON-LD (including @graph, ProductGroup and AggregateOffer), then microdata, then Open Graph, then the HTML itself, and for articles the readable text. The parser field says which source produced the record, and found says whether one was found at all.
Normalised values
Product offers come with a price as a decimal string, so no precision is lost: 1.299,00 € becomes "1299.00", with the currency as an ISO 4217 code in currency. availability is always one of in_stock, out_of_stock, preorder, backorder, discontinued, limited or unknown. Missing fields are null or empty lists, never left out, so your code does not need to guess.
Article records include authors, publish and modified times, and the body as Markdown. Metadata records hold the title, canonical URL, language, Open Graph tags, linked feeds, language alternates and every JSON-LD block on the page. The Data API docs list every field.
When there is no structured data: AI extraction
Not every page has structured data, and not every field you need is in schema.org. For those cases, AI extraction reads the page and returns JSON that matches a JSON Schema you define:
curl https://api.siftzo.com/v1/extract \
-H "X-API-Key: $SIFTZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/plans",
"schema": {
"type": "object",
"properties": {
"plans": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"monthly_price": { "type": "string" },
"seats": { "type": ["integer", "null"] }
},
"required": ["name", "monthly_price", "seats"]
}
}
},
"required": ["plans"]
},
"prompt": "Prices as decimal strings without currency symbols."
}'The response's data always validates against your schema. On the Data API, llm_fallback: true runs AI extraction with a fixed schema only when the parsers find nothing for a product or article, so you pay for it only on the pages that need it. Token-based pricing is on the pricing page.
What is deliberately left out
Products carry only the aggregate rating (value, best and count), never individual reviews, because reviews contain reviewers' names. Contact fields such as email, telephone and address are removed from JSON-LD, and there are no Data API sources for people.
The same thinking applies to your own extraction schemas: ask for the facts you need about products and content, not about individuals. See the responsible use docs.
If you track prices over time, the price monitoring use case shows how product records fit into a scheduled pipeline, and the guide on webhooks and polling covers collecting results from large runs.
Try it on your own data
1,000 free credits every month, no card needed. Failed requests are never billed.
Questions
Which structured data formats does the Data API read?
JSON-LD (including @graph, ProductGroup and AggregateOffer), microdata and Open Graph, then the page HTML. For articles it also reads the main text of the page.
How are prices returned?
As decimal strings with a period as the decimal separator, for example "1.299,00 €" becomes "1299.00", with the currency as an ISO 4217 code in a separate field.
What happens if a page has no structured data?
The record is null and found is false. With llm_fallback: true on product or article requests, AI extraction reads the page with a fixed schema instead.
Does the Data API return product reviews?
No. It returns only the aggregate rating, because individual reviews contain reviewers' names.