Reference

Data API

Get a product, an article or a page's metadata as a record with fixed fields. Siftzo reads the structured data the page already has, so most requests cost the same as a scrape.

GET and POST /v1/data/{source}

source is product, article or metadata. Use GET with query parameters or POST with the same fields as a JSON body. Unknown fields are rejected with 400 invalid_request.

urlstringrequired
The page to read. The same rules as for POST /v1/scrape.
renderauto | never | alwaysdefault auto
How the page is fetched. See Rendering.
countrystring
Exit country as an ISO 3166-1 alpha-2 code.
timeout_msintegerdefault 30000
5,000–50,000. The deadline for the whole request.
llm_fallbackbooleandefault false
product and article only. When the parsers find nothing, run AI extraction with a fixed schema for the source. Priced as extraction.
curl -G https://api.siftzo.com/v1/data/product \
  -H "X-API-Key: $SIFTZO_API_KEY" \
  --data-urlencode "url=https://shop.example/p/1" \
  -d llm_fallback=true

Response

200 OK
{
  "id": "01K74F1C6T9P3VX2HQ8M4RZDJA",
  "status": "done",
  "source": "product",
  "url": "https://shop.example/p/1",
  "final_url": "https://shop.example/p/1",
  "status_code": 200,
  "found": true,
  "parser": "json-ld",
  "fallback": null,
  "record": {
    "name": "Trail Running Shoe",
    "description": "Lightweight shoe for rough trails.",
    "brand": "Example",
    "sku": "TRS-42",
    "gtin": "05712345678901",
    "mpn": null,
    "url": "https://shop.example/p/1",
    "images": ["https://shop.example/img/trs-42.jpg"],
    "category": "Shoes",
    "offers": [
      {
        "price": "119.95",
        "currency": "EUR",
        "availability": "in_stock",
        "url": "https://shop.example/p/1",
        "seller": "Example Shop"
      }
    ],
    "rating": { "value": 4.6, "best": 5, "count": 213 }
  },
  "warnings": [],
  "tier": "http",
  "attempts": 1,
  "credits": 1,
  "credits_detail": { "scrape": 1, "llm": 0 },
  "duration_ms": 812
}
idstring
Request ID, the same as the X-Request-Id header.
statusdone | failed
Whether the page was fetched.
sourcestring
The source you asked for.
url, final_url, status_code
The page as fetched, after redirects.
foundboolean
Whether a record was found. false still has status: "done" and record: null, and the scrape is billed.
parserstring | null
Where the record came from: json-ld, microdata, opengraph, html, readability or llm.
fallbacknull | "llm"
"llm" when the record came from the AI fallback.
recordobject | null
The record, described below. Missing fields are null or empty lists, never left out.
warningsstring[]
Notes from the parsers, if any. Empty when there is nothing to report.
tier, attempts
As for a scrape.
creditsinteger
Credits charged, split in credits_detail (scrape, llm).
duration_msinteger
Time spent inside Siftzo, in milliseconds.

How a record is found

Siftzo scrapes the page and reads the structured data it already has (JSON-LD, microdata, Open Graph), then the HTML itself, and for articles the readable text. parser tells you which one produced the record. When none finds anything, found is false, or, with llm_fallback: true, AI extraction reads the page with a fixed schema and fallback is "llm".

Records

product

name, description, brand, category, urlstring | null
As the page states them.
sku, gtin, mpnstring | null
Product identifiers.
imagesstring[]
Absolute image URLs.
offersarray
price (a string such as "19.99", so no precision is lost), currency (ISO 4217), availability, url and seller. availability is one of in_stock, out_of_stock, preorder, backorder, discontinued, limited or unknown.
ratingobject | null
value (number), best (number or null) and count (integer or null).

article

title, description, publisher, language, section, image, urlstring | null
As the page states them.
authorsstring[]
Author names.
published_at, modified_atstring | null
RFC 3339 timestamps.
body_markdownstring | null
The article text as Markdown.
word_countinteger | null
Words in the body.

metadata

title, description, canonical_url, language, site_name, favicon, robotsstring | null
From the page head.
open_graph, twitterobject
og:* and twitter:* meta tags as key–value pairs.
json_ldobject[]
Every JSON-LD block on the page, parsed. Contact fields (email, telephone, faxNumber, address, contactPoint) are removed.
feedsarray
Linked feeds: url, type (rss, atom or json) and title.
alternatesarray
Language versions: hreflang and url.

The Data API is for products, articles and page metadata. There are no sources for people, and contact details are removed from JSON-LD. See Responsible use.

Errors

The same as for a scrape: refused requests return an error object, and pages that could not be fetched return the result with status: "failed". With the fallback, the errors of AI extraction can also occur, such as 402 llm_tokens_exhausted. See Errors.

Credits

A Data API request costs the same as a scrape on the tier that fetched the page: 1 credit over HTTP, 10 in a browser. A request that finds nothing is still billed, since the page was fetched. When the AI fallback runs, its tokens are added as for AI extraction.

Example: 1,000 product pages over HTTP where 950 have JSON-LD and 50 need the fallback at about 6,000 input and 600 output tokens each: 1,000 × 1 + 50 × ⌈(6,000 × 2 + 600 × 10) / 300⌉ = 1,000 + 50 × 60 = 4,000 credits.