---
title: Core concepts - how the API works
description: 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.
order: 2
---

# 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](/scraper-api) works the same way.

## The one request shape

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

```http
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](/docs/guides/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.

```bash
# 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.

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

Browse every dedicated endpoint in the [scraper directory](/scraper-api): 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.

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

In the [scraper directory](/scraper-api), cards marked **via Universal** route through this endpoint. Full details on the [Universal Web Scraper API](/docs/endpoints/universal) page.

| | Dedicated endpoint | Universal Web Scraper API |
|---|---|---|
| Path | `/api/v1/{site}/{resource}` | `/api/v1/universal/get` |
| Input | `query` (id, URL, or keyword) | `url` (any web page) |
| Output | Validated structured JSON | HTML, text, or auto-parsed JSON |
| Best for | Supported site + page type | Any 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:

| Resource | What it returns | Example sites |
|---|---|---|
| `search` | Ranked results for a keyword query | `google`, `bing`, `walmart`, `ebay`, `youtube` |
| `product` | A single product page | `walmart`, `ebay`, `target`, `bestbuy`, `etsy` |
| `article` | A single news or blog article | `bbc`, `reuters`, `techcrunch`, `medium` |
| `job` | A single job posting | `indeed`, `linkedin`, `glassdoor` |
| `property` | A real-estate listing | `zillow`, `redfin`, `realtor` |
| `profile` | A public profile page | `github`, social sites, directories |
| `quote` | A finance quote | `yahoo-finance`, `tradingview` |
| `video` | A single video page | `youtube`, `vimeo` |

Learn the request/response shape for one resource and it carries to every site that exposes it. The [Endpoint reference](/docs/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:

| Action | Credits |
|---|---|
| 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](/docs/guides/billing) for the full policy and [pricing](https://chocodata.com/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 `404`s 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](/docs/guides/billing).

## 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](/docs/guides/errors).

## Where to go next

- [Getting started](/docs/getting-started) - your first call in under 2 minutes.
- [Endpoint reference](/docs/endpoint-reference) - the resource model and how to find any endpoint.
- [Universal Web Scraper API](/docs/endpoints/universal) - scrape any URL to JSON, HTML, or text.
- [Scraper directory](/scraper-api) - browse all 453 endpoints.
- [Dashboard playground](https://app.chocodata.com) - run any endpoint live and copy the request.