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 | alwaysdefaultauto- How the page is fetched. See Rendering.
countrystring- Exit country as an ISO 3166-1 alpha-2 code.
timeout_msintegerdefault30000- 5,000–50,000. The deadline for the whole request.
llm_fallbackbooleandefaultfalseproductandarticleonly. 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=trueconst res = await fetch("https://api.siftzo.com/v1/data/product", {
method: "POST",
headers: {
"X-API-Key": process.env.SIFTZO_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({ url: "https://shop.example/p/1", llm_fallback: true }),
signal: AbortSignal.timeout(120_000),
});
const result = await res.json();
if (!res.ok) throw new Error(result.error.code);
if (result.found) {
const offer = result.record.offers[0];
console.log(result.record.name, offer?.price, offer?.currency, result.parser);
}import os
import requests
res = requests.post(
"https://api.siftzo.com/v1/data/product",
headers={"X-API-Key": os.environ["SIFTZO_API_KEY"]},
json={"url": "https://shop.example/p/1", "llm_fallback": True},
timeout=120,
)
result = res.json()
res.raise_for_status()
if result["found"]:
record = result["record"]
print(record["name"], record["offers"][0]["price"] if record["offers"] else None)package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
func main() {
payload, _ := json.Marshal(map[string]any{"url": "https://shop.example/p/1", "llm_fallback": true})
req, _ := http.NewRequest("POST", "https://api.siftzo.com/v1/data/product", bytes.NewReader(payload))
req.Header.Set("X-API-Key", os.Getenv("SIFTZO_API_KEY"))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 120 * time.Second}
res, err := client.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var result struct {
Found bool `json:"found"`
Parser string `json:"parser"`
Record *struct {
Name string `json:"name"`
Offers []struct {
Price string `json:"price"`
Currency string `json:"currency"`
} `json:"offers"`
} `json:"record"`
}
json.NewDecoder(res.Body).Decode(&result)
if result.Found {
fmt.Println(result.Record.Name, result.Parser)
}
}Response
{
"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.
falsestill hasstatus: "done"andrecord: null, and the scrape is billed. parserstring | null- Where the record came from:
json-ld,microdata,opengraph,html,readabilityorllm. fallbacknull | "llm""llm"when the record came from the AI fallback.recordobject | null- The record, described below. Missing fields are
nullor 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.
offersarrayprice(a string such as"19.99", so no precision is lost),currency(ISO 4217),availability,urlandseller.availabilityis one ofin_stock,out_of_stock,preorder,backorder,discontinued,limitedorunknown.ratingobject | nullvalue(number),best(number or null) andcount(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, twitterobjectog:*andtwitter:*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,atomorjson) andtitle. alternatesarray- Language versions:
hreflangandurl.
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.