Extract figures

POST/api/v1/extract/figureshttps://api.webcite.co

When to use it

Keep the source label, sheet, cell, and other provenance with each figure. A missing number is unknown, not zero. scale describes an already normalized value; do not apply the scale again.

Request

2 credits for a billable extraction outcome.

Examples run on your server. Set WEBCITE_API_KEY first. Python examples use the requests package.

curl

curl --fail-with-body -X POST 'https://api.webcite.co/api/v1/extract/figures' \
  -H "x-api-key: $WEBCITE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "asset_id": "YOUR_ASSET_ID"
}'

Request body

asset_idstring

An uploaded asset id (from POST /upload). One of asset_id / asset_url is required.

asset_urlstring

A direct URL to the file. One of asset_id / asset_url is required.

Response

Returns figures with available metric, value, unit, period, entity, basis, and provenance fields. Preserve decimalValue when supplied for exact arithmetic.

200 response

application/json

codestring | nullrequired

The stable classification of reason, safe to switch on. The same vocabulary and the same values as POST /extract. Null when nothing refused.

Code	What it means	What to do
`source_too_large`	a size or expansion ceiling refused the read	`reason` carries the observed value and the limit; send a smaller file
`source_encrypted`	the container is password-protected	send an unlocked copy
`source_corrupt`	the container could not be opened as the format it declares	re-export the file
`unsupported_format`	no reader is registered for this format	convert it
`ocr_unavailable`	the page had no text layer and no vision provider is configured	configure a vision key, or send a text-layer file
`partial_extraction`	some of the source was recovered and some was not	use what came back
`empty_source`	the source was read and held nothing	a fact about the file, not a failure , nothing to retry
`extraction_error`	our failure	retry

Values: "source_too_large""source_encrypted""source_corrupt""unsupported_format""ocr_unavailable""partial_extraction""empty_source""extraction_error"

figuresobject[]required

Every known metric found, as { metric, value, unit, entity?, period?, band, bound, provenance }. Empty both when the document held no recognised metric and when the read was refused.

reasonstring | nullrequired

Free text naming the cause, straight from whatever refused or failed , spreadsheet_magic_mismatch:xlsx, spreadsheet_too_large:bytes:33554433>33554432, extraction_failed:File is password-protected. Carries detail no enum can, and is NOT stable: it includes dependency error text. Display it; do not branch on it. Null when nothing refused.

statestringrequired

How much of the source the read recovered, in one word. complete on a healthy read, whatever the payload beside it turned out to contain.

Values: "complete""partial""unsupported""error"

Errors

For 400, check the request fields and source identifiers. For 401, check your API key. For 429, wait for the retry interval. See the errors guide before retrying a billable request.

400: Asset not found
401: Unauthorized - API key required
429: Rate limit exceeded

Error handling and retry guidance