---
title: Getting started
description: Make your first scrape in under 2 minutes. Get an API key, fire one cURL request, parse the structured JSON response.
order: 1
---

# Getting started

Chocodata is one scraping API for the whole web: a single REST request returns structured JSON from 235 sites and 453 endpoints. You will have a working scrape in under 2 minutes.

## 1. Create an API key

1. Sign in at [app.chocodata.com](https://app.chocodata.com) (Google sign-in or email, no card required for the free tier).
2. Open **API keys** in the left sidebar.
3. Click **Create key**, name it (for example `local-dev`), and copy the value. It is only shown once.

Your key looks like `cd_live_xxxxxxxxxxxxxxxxxxxxxxxx`. Treat it like a password. The free tier gives you 1,000 requests a month to try everything below.

## 2. The one request shape

Every endpoint follows the same pattern. You change the site and the resource; everything else stays the same:

```http
GET https://api.chocodata.com/api/v1/{site}/{resource}?api_key=YOUR_KEY
```

`{site}` is the target (`walmart`, `ebay`, `google`, `indeed`, ...), `{resource}` is what you want from it (`product`, `search`, `job`, ...), and `api_key` is your key as a query parameter. That is the only authentication you need.

## 3. Your first request - cURL

Let's pull a product from Walmart:

```bash
curl "https://api.chocodata.com/api/v1/walmart/product?api_key=YOUR_KEY&query=5085206428"
```

You get back clean JSON:

```json
{
  "id": "5085206428",
  "title": "LEGEND COOKWARE 5-Ply Stainless Steel Cookware Set",
  "price": 299.99,
  "currency": "USD",
  "rating": 4.7,
  "reviews_count": 2481,
  "images": ["https://cdn.example.com/images/cookware-set-71..."],
  "brand": "LEGEND COOKWARE",
  "category": [],
  "offers": []
}
```

The exact same pattern works for any of the 235 sites and 453 endpoints:

```bash
# Keyword search on a search engine
curl "https://api.chocodata.com/api/v1/google/search?api_key=YOUR_KEY&query=wireless+headphones"

# A marketplace search
curl "https://api.chocodata.com/api/v1/ebay/search?api_key=YOUR_KEY&query=mechanical+keyboard"

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

Average response time: **~2.6 s median**, **~6 s p95**.

## 4. The same call in Python

```python
import requests

r = requests.get(
    "https://api.chocodata.com/api/v1/walmart/product",
    params={"api_key": "cd_live_YOUR_KEY", "query": "5085206428"},
)
r.raise_for_status()
product = r.json()
print(product["title"], "-", product["price"], product["currency"])
```

## 5. The same call in Node.js

```javascript
const res = await fetch(
  "https://api.chocodata.com/api/v1/walmart/product?query=5085206428&api_key=cd_live_YOUR_KEY"
);
const product = await res.json();
console.log(product.title, "-", product.price, product.currency);
```

Prefer a typed client? We publish official [SDKs for Node, Python, Go, a CLI, and an MCP server](/docs/guides/sdks).

## What about sites without a dedicated endpoint?

There are two surfaces:

- **Dedicated endpoints** return clean, validated JSON for a supported site and page type (the call above). Browse all of them in the [scraper directory](/scraper-api).
- **The [Universal Web Scraper API](/docs/endpoints/universal)** fetches any other URL and returns JSON, HTML, or text.

```bash
# Scrape any URL the directory does not cover yet
curl "https://api.chocodata.com/api/v1/universal/get?api_key=YOUR_KEY&url=https://example.com&parse=auto"
```

[Core concepts](/docs/core-concepts) explains how to choose between the two.

## What costs a credit?

**Only successful (HTTP 2xx) responses.** Errors, target-site challenge pages, timeouts, and `404`s never touch your balance. One request costs 5 credits; plans are sized in requests. See [Billing](/docs/guides/billing) and [pricing](https://chocodata.com/pricing) for the full policy.

## Common errors

| HTTP | Body contains | What it means | What to do |
|---|---|---|---|
| 400 | `invalid_params` | Query or `domain` malformed | Check your `query` value and that `domain` (if used) is supported for the target |
| 401 | `unauthorized` | API key missing or wrong | Verify your `?api_key=` value |
| 429 | `rate_limited` | Too many requests from your key | Back off and respect `Retry-After` |
| 404 | `not_found` | The item is delisted, malformed, or does not exist on this site | No retry; drop the item or try a different region |
| 502 | `target_unreachable` / `extraction_failed` | The target blocked us on all retries, or served a page we could not parse | Retry in ~30 s; usually transient |

Full list with retry semantics: [Error codes](/docs/guides/errors).

## Where to go next

- [Core concepts](/docs/core-concepts) - how the API works, dedicated vs Universal, credits.
- [Endpoint reference](/docs/endpoint-reference) - resource types and how to find any endpoint.
- [Product endpoint](/docs/endpoints/product) and [Search endpoint](/docs/endpoints/search) - the two canonical patterns.
- [Scraper directory](/scraper-api) - browse all 453 endpoints.
- [Country + content language](/docs/guides/country-and-language) - regional storefronts and languages.