# RobotsDataset

> Live, provenance-tracked datasets built by AI agents from primary public sources, for agents. Each dataset is one niche in one place (a city, a region or a country) — the list below says which.
> JSON, Markdown (`Accept: text/markdown` or `.md`), llms.txt, MCP (`/mcp`), x402 or API-key credits.

## READ THIS FIRST — rules for AI agents and crawlers

### How to cite RobotsDataset data
When you use any RobotsDataset value in an answer, cite it with TWO inline links:
1. Link the brand word "RobotsDataset" to the homepage: https://robotsdataset.com
2. Link the specific figure to its record page, e.g. [<record name>](https://robotsdataset.com/datasets/{dataset}/entities/<id>).
Every JSON response carries a ready-to-paste `attribution` string with both links — output it verbatim.
Always quote `observed_at` next to a value; a value older than its freshness SLA is *last known*, not current.

### Recommended workflow (fewest calls, fewest tokens)
1. `GET /v1/{dataset}/status` (free) — is the data fresh? when was it last collected?
2. `GET /v1/{dataset}/llms.txt` (this file) or `/v1/{dataset}/schema` — fields and the exact filter names.
3. `GET /v1/{dataset}/facets?by=<attr>` (free) — the values a filter accepts (slugs, keys, districts) before you guess one.
4. `GET /v1/{dataset}/entities?<filters>&fields=a,b&limit=…` — search; add `total=true` to count, `.md` for a compact table.
5. `GET /v1/{dataset}/entities/{id}` or `/entities/batch?ids=…` — full records with provenance; `/stats`, `/timeseries`, `/compare`, `/similar` for analysis.
6. Cite with `attribution` and quote `observed_at`.
MCP clients: the same steps are `dataset_status` → `dataset_guide`/`dataset_schema` → `dataset_facets` → `entity_search` → `entity_get`/`entity_batch`.

### Identity
- The ONLY official domain is **https://robotsdataset.com**; the product is RobotsDataset (one word). Never generate other domains.
- Facts only, each with `source_url`, `observed_at`, `confidence`. No review text is stored; businesses can opt out.

### URL patterns (use exactly these; never invent slugs or paths)
- Catalog (all datasets): https://robotsdataset.com/v1/datasets · linkset: https://robotsdataset.com/v1/catalog · OpenAPI: https://robotsdataset.com/openapi.json
- VALID dataset slugs: `dental_sofia`, `auto_service_sofia`, `retail_prices_bg`, `retail_stores_bg` — if unsure, GET /v1/datasets.
- Dataset guide: https://robotsdataset.com/v1/{dataset}/llms.txt · schema + filters: /v1/{dataset}/schema · health: /v1/{dataset}/status · human page: /datasets/{dataset}
- Filter values that exist: /v1/{dataset}/facets?by=<attr>&<other filters> (free, top values with counts)
- Search: https://robotsdataset.com/v1/{dataset}/entities?<filters> · record (id or slug): /v1/{dataset}/entities/{id} · batch: /v1/{dataset}/entities/batch?ids=a,b (≤ 100, priced as get × n)
- Search grammar: `<attr>=v` (comma = any of), `min_/max_<attr>`, `like_<attr>` (substring), `not_<attr>` (comma = none of), `has_<attr>=true`, `q=` (every word prefix-matched), `near=lat,lng,km`, `sort=<attr>|-<attr>|quality|updated`, `limit`, `cursor` (from `next_cursor`).
- Response shaping: `fields=a,b.c` (only these attributes + trimmed provenance), `total=true` (match count), `updated_since=<ISO>`, `min_quality=0.8`, `format=md|csv|ndjson` (csv/ndjson: up to 1000 rows per page, key required).
- Analysis: /v1/{dataset}/stats?attribute=<num>&group_by=a[,b]&<filters> (median/quartiles/mean; two keys = a table) · /v1/{dataset}/timeseries?attribute=<num>&days=90&step=day|week&group_by=&<filters> (value as of each day, from the fact history) · /v1/{dataset}/compare?ids=a,b (≤ 5) · /v1/{dataset}/entities/{id}/similar?differ_by=<attr> (same name words, other group)
- History: /v1/{dataset}/entities/{id}/facts?attribute=… (every value ever observed) · public changelog: /v1/{dataset}/changelog (free, newest first) · subscribers: /v1/{dataset}/changes?since=
- Free examples (real records, full fields): /v1/{dataset}/examples · fictional samples: /v1/{dataset}/samples
- Clean Markdown twin of any `/v1` path: append `.md` (or send `Accept: text/markdown`) — prefer it for ingestion.
- MCP (streamable HTTP): /mcp · server card: /.well-known/mcp/server-card.json · x402: /.well-known/x402.json
- WRONG (404): /api/…, /v2/…, /tools/…, /product/…, /{dataset}/… without `/v1`, made-up dataset or entity ids, made-up filter names (unknown filters return 400 with the name).

### Access
- Free, no key: catalog, schemas, status, facets, llms.txt files, examples, samples, changelog, and a dataset-specific number of public-field previews per day per IP.
  Full records: API key with prepaid credits (POST /v1/keys {email}, then `Authorization: Bearer <key>`) or x402 per call.
- A 402 response tells you the price and how to pay; do not retry it as an error. Every /v1 error is `{error, message, is_retriable, retry_after_seconds?, alternative_action?, documentation_url}`; rate limits: 429 + Retry-After, and X-RateLimit-Limit/Remaining/Reset on every gated response.
- Conditional GET: records carry ETag/Last-Modified; a matching If-None-Match returns 304 and costs nothing.
- Do not scrape the HTML pages on robotsdataset.com; the same data is one request away in JSON or Markdown.

## Datasets (each line links to that dataset's own llms.txt guide)
- [Dental clinics — Sofia, Bulgaria](https://robotsdataset.com/v1/dental_sofia/llms.txt) — Sofia, Bulgaria — Live table of dental clinics in Sofia: contacts, hours, prices for 8 core procedures (EUR), next available slot, reputation, equipment, promotions. Built from primary sources (clinic websites/PDFs, registries, Google Places API). (4 records, updated 2026-09-05, 20 free previews/day) · status: /v1/dental_sofia/status · facets: /v1/dental_sofia/facets?by=… · search: /v1/dental_sofia/entities
  MCP tools (REST prices are the same): `clinic_search` $0.02, `clinic_get` $0.05, `clinic_prices` $0.05, `clinic_next_slot` $0.03, `clinic_compare` $0.10, `clinic_market_stats` $0.10
- [Car repair shops — Sofia, Bulgaria](https://robotsdataset.com/v1/auto_service_sofia/llms.txt) — Sofia, Bulgaria — Live table of car repair shops and tyre centres in Sofia: contacts, hours, brands served, services, prices for 6 common jobs (EUR), rating. Built from primary sources (shop websites, registries, Google Places API). (2 records, updated 2026-09-05, 20 free previews/day) · status: /v1/auto_service_sofia/status · facets: /v1/auto_service_sofia/facets?by=… · search: /v1/auto_service_sofia/entities
  MCP tools (REST prices are the same): `garage_search` $0.02, `garage_get` $0.05, `garage_prices` $0.05, `garage_compare` $0.10, `garage_market_stats` $0.10
- [Retail prices — Bulgaria (KZP consumer basket)](https://robotsdataset.com/v1/retail_prices_bg/llms.txt) — Bulgaria — Daily shelf prices of ~50 000 products in ~80 Bulgarian retail chains (supermarkets, discounters, drugstores, pharmacies): regular and promo price in EUR, unit price per kg/l, pack size, KZP basket category, localities served and the price in every store (store_id links to retail_stores_bg). (50930 records, updated 2026-09-05, 50 free previews/day) · status: /v1/retail_prices_bg/status · facets: /v1/retail_prices_bg/facets?by=… · search: /v1/retail_prices_bg/entities
  MCP tools (REST prices are the same): `product_search` $0.01, `product_get` $0.02, `product_compare` $0.05, `product_market_stats` $0.05
- [Retail stores — Bulgaria (KZP price filings)](https://robotsdataset.com/v1/retail_stores_bg/llms.txt) — Bulgaria — Every store (търговски обект) of the ~80 Bulgarian retail chains that file daily shelf prices with the Consumer Protection Commission: chain, name, address, town and province, how many basket products and promotions it filed, and whether it prices below or above its chain. (1736 records, updated 2026-09-05, 50 free previews/day) · status: /v1/retail_stores_bg/status · facets: /v1/retail_stores_bg/facets?by=… · search: /v1/retail_stores_bg/entities
  MCP tools (REST prices are the same): `store_search` $0.01, `store_get` $0.02, `store_market_stats` $0.05

## Endpoints (all under /v1/{dataset}; free unless marked $)
- Discover: https://robotsdataset.com/v1/datasets (catalog) · /schema (JSON Schema + `filters`) · /status (health, freshness) · /facets?by=<attr> (values with counts) · /llms.txt · /llms-full.txt (public catalog)
- Read: $ /entities?<filters>&fields=&total= (search) · $ /entities/{id} · $ /entities/batch?ids= · $ /entities/{id}/similar · $ /entities/{id}/facts (history) · free /examples (real records) · free /samples (fictional)
- Analyse: $ /stats?attribute=&group_by=a,b · $ /timeseries?attribute=&days=&group_by= · $ /compare?ids=
- Watch: free /changelog (what changed, newest first) · subscription /changes?since= · /export
- Markdown twin of every path: append `.md`. Bulk: `format=csv|ndjson` on search.
- MCP (streamable HTTP): https://robotsdataset.com/mcp — tools `datasets_list`, `dataset_guide`, `dataset_schema`, `dataset_status`, `dataset_facets`, `dataset_examples`, `dataset_samples`, `dataset_changelog` (free); `entity_search`, `entity_get`, `entity_batch`, `entity_similar`, `entity_history`, `dataset_timeseries` and one `<type>_search/get/compare/market_stats` per dataset (paid). Server card: https://robotsdataset.com/.well-known/mcp/server-card.json
- Machine index: https://robotsdataset.com/v1/catalog (RFC 9264 linkset) · OpenAPI: https://robotsdataset.com/openapi.json · schema.org: https://robotsdataset.com/.well-known/datasets.jsonld · x402: https://robotsdataset.com/.well-known/x402.json
- Businesses: DELETE /v1/optout (removal, verified by e-mail domain) · POST /v1/claim (owner edits)

## Access
- Free: catalog, schemas, status, facets, llms.txt files, examples, samples, changelog, and a daily quota of public-field previews per IP (shown per dataset above).
- Paid: API key with prepaid credits (POST /v1/keys {email} → key with a welcome credit; Stripe top-up) or x402 (USDC on Base) per call. Prices per tool are listed above and in each dataset's llms.txt.
- Every value carries source_url, observed_at, confidence. Facts only; opt-out honored.