Extract Structured JSON from Webpages

Turn a public webpage into JSON fields using a natural-language instruction. Use the results in research, content enrichment and application workflows. Describe the fields you need, then validate those fields before saving or using the response.

View API details or try the Demo.

Request

Send POST /v1/websitetools/url2json with appkey in the query string and url and prompt in the JSON body. Both body fields are required. The public URL must use HTTP or HTTPS on port 80 or 443, cannot contain credentials, and is limited to 2,048 characters. The prompt is limited to 100,000 Unicode characters and 512 KiB as UTF-8.

curl 'https://api.gugudata.io/v1/websitetools/url2json?appkey=YOUR_APPKEY' \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://example.com","prompt":"Extract the page title as title."}'

Keep your AppKey in trusted server-side code. Do not embed it in a public webpage.

Read the response

The successful response uses the existing dataStatus and data envelope. For the request above, the expected extracted data is:

{"title":"Example Domain"}

Field	Type	Meaning
dataStatus.statusCode	integer	200 for a successful extraction.
dataStatus.requestParameter	string	Website host, path and instruction length; not the full instruction.
data	object	Fields determined by your extraction instruction.
data.articles	array, when applicable	Article arrays with title and url.
data.items	array, when applicable	Other array results.

The API does not require every response to contain title or articles. Those are examples, not a fixed schema for every extraction task. An explicitly empty list, such as {"items":[]}, is a valid no-match result. A missing result is not the same as an empty list. Numeric zero and boolean false are valid field values.

Extraction quality depends on the webpage and your instruction. Ask for specific fields and verify the output against your application’s requirements.

Try a repeatable Demo

The Demo extracts the three article titles and links from this public sample page: Document workflows, Website data extraction and API integration. Open the page to see exactly what is being extracted.

curl 'https://api.gugudata.io/v1/websitetools/url2json/demo'

The response contains data.articles. Successful Demo results are cached for 15 minutes. X-GuGuData-Demo-Mode identifies live or cached; X-GuGuData-Generated-At indicates when the result was generated. A failed extraction returns an error, not substitute sample articles.

Handle failures

HTTP	Business code	Meaning
400	400	Missing or invalid URL, instruction or JSON body.
401 / 403	Existing authentication code	Missing access or an invalid/unauthorized AppKey.
422	500	No structured content could be extracted; an empty object is not a successful result.
429	Existing rate-limit code	Request limit reached.
502	500	Extraction failed, timed out, or returned an invalid result.
503	500	Extraction is temporarily unavailable.
500	500	Unexpected internal failure.

Check the HTTP status before reading data. For a 422, review the page and make the instruction more specific. Do not automatically repeat failed extraction requests in a tight loop: another attempt can consume time and usage. Log only the status and your own request reference, not private instructions or extracted content.

Related APIs

• Readable article content
• Article image extraction
• Website metadata

See the OpenAPI reference for the full response envelope and authentication requirements.