Chocodata

Docs

ChatGPT Claude

Core concepts - how the API works

One request shape for the whole web. Dedicated specific-item endpoints vs the Universal scraper, the credit model, and how you only pay for successful responses.

Core concepts

Chocodata is one web-scraping API for the whole web. Instead of learning a different API for every site, you learn a single request shape and point it at whichever site and resource you need. Today that covers 235 sites, 453 endpoints, and 17 categories, with 210 dedicated specific-item endpoints and 250+ endpoints returning validated, structured JSON. Anything without a dedicated endpoint is still scrapable through the Universal Web Scraper API.

This page explains the model. Once you have it, every endpoint in the scraper directory works the same way.

The one request shape

Every dedicated endpoint is a GET request in exactly this form:

GET https://api.chocodata.com/api/v1/{site}/{resource}?api_key=YOUR_KEY
  • {site} is the target, for example walmart, ebay, google, indeed, zillow, github, youtube.
  • {resource} is what you want from that site, for example product, search, job, property, profile, video.
  • api_key is your key, passed as a query parameter. That is the only authentication mechanism. See Authentication.

Most resources take a query parameter (an identifier, a URL, or a keyword) plus optional modifiers like domain, language, or pages. The same envelope holds across every site, so once you have called one endpoint you can call all of them.

# A job listing on Indeed
curl "https://api.chocodata.com/api/v1/indeed/job?api_key=YOUR_KEY&query=https://www.indeed.com/viewjob?jk=abc123"

# A repository on GitHub
curl "https://api.chocodata.com/api/v1/github/repository?api_key=YOUR_KEY&query=facebook/react"

# A keyword search on Bing
curl "https://api.chocodata.com/api/v1/bing/search?api_key=YOUR_KEY&query=best+running+shoes"

Two ways to scrape: dedicated endpoints vs Universal

There are two surfaces, and you choose based on whether the site and page type have a dedicated parser.

1. Dedicated specific-item endpoints (structured JSON)

A dedicated endpoint targets one site and one page type and returns clean, validated, structured JSON: named fields, correct types, no HTML to parse. Chocodata ships 210 dedicated specific-item endpoints (product, article, job, profile, listing, video, and more), and 250+ endpoints in total return validated JSON.

Use a dedicated endpoint when one exists for your target. You get a typed object instead of raw markup, and the parser is maintained for you when the site changes its layout.

GET /api/v1/{site}/{resource}?api_key=YOUR_KEY&query=...

Browse every dedicated endpoint in the scraper directory: cards marked JSON return structured data.

2. The Universal Web Scraper API (any URL)

For pages without a dedicated parser (or any arbitrary URL you want to fetch), use the Universal Web Scraper API. You hand it a URL, it handles proxies and anti-bot, and returns the page in the format you ask for: raw HTML, plain text, or auto-extracted JSON.

GET /api/v1/universal/get?api_key=YOUR_KEY&url=https://example.com&parse=auto

In the scraper directory, cards marked via Universal route through this endpoint. Full details on the Universal Web Scraper API page.

Dedicated endpointUniversal Web Scraper API
Path/api/v1/{site}/{resource}/api/v1/universal/get
Inputquery (id, URL, or keyword)url (any web page)
OutputValidated structured JSONHTML, text, or auto-parsed JSON
Best forSupported site + page typeAny other URL, or full-page HTML

Resources, not sites

The catalogue is organized by resource type, not by an exhaustive page-by-page list. A handful of resource types appear across hundreds of sites:

ResourceWhat it returnsExample sites
searchRanked results for a keyword querygoogle, bing, walmart, ebay, youtube
productA single product pagewalmart, ebay, target, bestbuy, etsy
articleA single news or blog articlebbc, reuters, techcrunch, medium
jobA single job postingindeed, linkedin, glassdoor
propertyA real-estate listingzillow, redfin, realtor
profileA public profile pagegithub, social sites, directories
quoteA finance quoteyahoo-finance, tradingview
videoA single video pageyoutube, vimeo

Learn the request/response shape for one resource and it carries to every site that exposes it. The Endpoint reference explains this model and how to find the exact resource for any site.

Credits and what a request costs

Usage is metered in credits. The conversion is simple:

ActionCredits
One request (dedicated endpoint or Universal)5
JavaScript rendering (when shipped, opt-in add-on)+10
Screenshot (when shipped, opt-in add-on)+10

Plans are sized in requests (1 request = 5 credits). The Free plan, for example, is 1,000 requests per month, which is 5,000 credits. Credits are the internal accounting unit; your plan and PAYG pricing are quoted in requests. See Billing for the full policy and pricing for plan limits.

render_js and screenshot are reserved today and return 501 not_implemented. They never cost anything until they ship.

You only pay for successful responses

Only successful (HTTP 2xx) responses are billed. Errors, anti-bot challenge pages, timeouts, and 404s never touch your balance. If we could not return usable data, you do not pay for it. Our orchestrator retries internally and bills at most once per request, only on a final 2xx. The full breakdown is in the Billing policy.

The response envelope

Every dedicated endpoint returns a flat JSON object of named fields for that resource. Successful responses also carry a small set of informational headers:

  • Asa-Cost - credits spent (5 for a standard request, 0 for any non-2xx).
  • Asa-Resolved-Url - the final target URL after redirects.
  • Asa-Source-Status - the target site’s own HTTP status.
  • Asa-Attempts - how many internal attempts it took to fetch the page.
  • Asa-Extractor-Version - the parser version, for example walmart@1.0.0.

Errors share one body shape across every endpoint, with a machine-readable error code, a request_id, and a docs_url. See Error codes.

Where to go next