Chocodata

Docs

ChatGPT Claude

SDKs, CLI & MCP

Install and first-request snippets for the official Node, Python, Go, CLI, and MCP integrations. Each wraps auth, retries, and structured errors.

SDKs, CLI & MCP

We publish official SDKs for Node, Python and Go, plus a CLI and an MCP server. Each wraps the HTTP API with retry and backoff on retryable failures, and a structured error type that tells you whether retrying will help. Pick the one that matches your stack.

SurfacePackageInstall
Node.js / TypeScriptchocodatanpm install chocodata
Pythonchocodatapip install chocodata
Gogithub.com/ChocoData-com/chocodata-gogo get github.com/ChocoData-com/chocodata-go
CLI (any language)chocodata-clinpm install -g chocodata-cli
MCP server (AI agents)chocodata-mcpnpx -y chocodata-mcp

Parameters differ per endpoint

This is the thing to know before you start. The API is not uniform, and the SDKs do not pretend otherwise:

  • amazon.product takes query (an ASIN or ISBN) or url
  • walmart.product takes url or id, and rejects query
  • bing.search takes q, not query

Each SDK exposes typed methods for the endpoints below, with that endpoint’s real parameter names, plus a generic call for the rest of the catalog.

Verified endpoints: amazon.product, amazon.search, walmart.product, walmart.search, ebay.product, ebay.search, bing.search, bing.images, tiktok.profile, youtube.video, instagram.profile. Everything else in the catalog works through the generic call.

Node / TypeScript

npm install chocodata
import { Chocodata } from "chocodata";

const chocodata = new Chocodata("asa_live_YOUR_KEY");

const product = await chocodata.amazon.product({ query: "0143127748" });
console.log(product.asin, product.title);

// Bing takes `q`
const images = await chocodata.bing.images({ q: "red panda", count: 20 });

// Anything without a typed method
const post = await chocodata.scrape("reddit", "post", {
  post_id: "627akk",
  subreddit: "askscience",
});

Node 18+, no runtime dependencies. Ships TypeScript types for every endpoint’s parameters.

Python

pip install chocodata
from chocodata import Chocodata

chocodata = Chocodata("asa_live_YOUR_KEY")

product = chocodata.amazon.product(query="0143127748")
print(product["asin"], product["title"])

images = chocodata.bing.images(q="red panda", count=20)

post = chocodata.scrape("reddit", "post", {
    "post_id": "627akk",
    "subreddit": "askscience",
})

Python 3.9+, standard library only. AsyncChocodata runs requests in worker threads via asyncio.to_thread, so calls compose with asyncio.gather; it is a concurrency wrapper, not a native async HTTP stack.

Go

go get github.com/ChocoData-com/chocodata-go
package main

import (
    "context"
    "fmt"
    "log"

    chocodata "github.com/ChocoData-com/chocodata-go"
)

func main() {
    client := chocodata.New("asa_live_YOUR_KEY")

    product, err := client.AmazonProduct(context.Background(), chocodata.Params{
        "query": "0143127748",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(product["asin"], product["title"])
}

Context-aware cancellation, zero dependencies beyond net/http. Scrape decodes into any target, so you can unmarshal straight into your own struct.

Note the module path is case-sensitive: ChocoData-com, not chocodata-com.

CLI

npm install -g chocodata-cli
chocodata login asa_live_YOUR_KEY     # stored in ~/.chocodata/config.json

The CLI mirrors the API’s shape: a target, a resource, then that endpoint’s parameters as flags.

chocodata amazon product --query 0143127748
chocodata amazon product --query 0143127748 --domain de
chocodata bing images --q "red panda" --count 20
chocodata tiktok profile --username rotana

# Pipe a list of IDs, one JSON object per line
cat asins.txt | chocodata amazon product --stdin-param query --ndjson > out.ndjson

Successful rows go to stdout and errors to stderr, so a partial failure still leaves a clean NDJSON stream for jq or a warehouse loader.

MCP server (Claude, Cursor, and other agents)

The MCP server exposes Chocodata as tools an AI agent can call directly. It runs over stdio and works with any MCP-compatible client.

{
  "mcpServers": {
    "chocodata": {
      "command": "npx",
      "args": ["-y", "chocodata-mcp"],
      "env": { "CHOCODATA_API_KEY": "asa_live_YOUR_KEY" }
    }
  }
}

Twelve tools: amazon_product, amazon_search, walmart_product, walmart_search, ebay_product, ebay_search, bing_search, bing_images, tiktok_profile, youtube_video, instagram_profile, and scrape for everything else. Each tool’s schema documents its own parameters, so the agent picks the right ones.

Raw HTTP (no SDK)

For stacks we don’t publish an SDK for (Java, Ruby, PHP, C#), the API is a plain GET with your key in the ?api_key= query parameter:

curl "https://api.chocodata.com/api/v1/amazon/product?api_key=asa_live_YOUR_KEY&query=0143127748"

There is no header auth: Authorization: Bearer and X-API-Key both return 401.

What the SDKs add over raw HTTP

  • Exponential backoff with jitter on retryable failures (429, 5xx, network).
  • A structured error type carrying the status, the API’s error code, the request id, and the server’s own retryable flag, so a 404 is never retried.
  • Typed parameters per endpoint, encoding the real contract rather than a uniform guess.
  • Sensible defaults: a 90s timeout you can override, and a User-Agent identifying the SDK and version.

Pass debug: true (Node), debug=True (Python) or WithDebug(true) (Go) to print every HTTP call with timings.

The Batch endpoint is available over raw HTTP; the SDKs do not wrap it yet.