# AI Find Me: requests and fields

All addresses are on https://aifindme.com. No key, CORS open for GET, JSON unless said otherwise.

## Search and lists

| Request | What you get |
|---|---|
| `GET /api/v1/businesses?q=<words>` | Full-text search over names, categories, cities, summaries, addresses, services, prices and FAQs. Words match as prefixes; accents are ignored. Without `q`: all listings, verified and complete ones first. |
| `&category=<key>` | One category; keys from `GET /api/v1/categories` (restaurant, cafe, bakery, bar, hotel, dentist, health, beauty, fitness, legal, finance, realestate, home, auto, retail, software, agency, education, events, travel, pets, creative, nonprofit, other). |
| `&city=<name>` | One city, written as people write it ("Amsterdam"); values from `GET /api/v1/cities`. |
| `&kind=shop` | Only web shops. Results then carry `shop.platform`, `shop.productCount`, `shop.categories`, `shop.products` (address). |
| `&country=NL` or `&country=US` | One country (ISO code). The directory covers the Netherlands, Belgium and the United States; every result carries `country`. |
| `&verified=1` | Only listings the owner verified. |
| `&open=now` | Only businesses open right now, judged from their structured hours in their own time zone; listings without such hours are left out. |
| `&fields=slug,name,phone,website` | Only these fields of each result (`slug` always comes). |
| `&limit=<1-50>&offset=<0-10000>` | Paging; `total` says how many match in all. |
| `GET /api/v1/new?since=<YYYY-MM-DD>&kind=shop&country=US` | Listings added since a date (at most 90 days back), newest first, with `listedSince`; `country` keeps one country. Also an Atom feed at `/feed/new.xml` (same parameters) and the pages `/new` and `/new/shops`. |

## One business

| Request | What you get |
|---|---|
| `GET /api/v1/businesses/<slug>` | The full fact card as JSON: every fact, `directory.sources` (the origin of each fact), `directory.verification` (`owner-verified`, `claimed`, `unclaimed`), `directory.lastChecked`, `directory.lastChanged`, `directory.completeness`, `directory.status` (`active` or `inactive`), `directory.attributions`, and `shop` for web shops. 404: no such listing; 410: removed. |
| `GET /b/<slug>.md` | The same card as Markdown (also `Accept: text/markdown` on `/b/<slug>`). |
| `GET /b/<slug>/llms.txt` | A short index of the business with its official links. |
| `GET /api/v1/businesses/<slug>/products` | A web shop's products (name, price, currency, stock, link, image) with the shop facts around them. |
| `GET /b/<slug>?view=ai` | The page as the AI view: lean, labelled HTML with the same facts and links as the human page. |

## Sources of a fact (`directory.sources[field].source`)

`structured data` (schema.org on the website, the most reliable), `page metadata`, `page text`, `shop platform data`
(Shopify/WooCommerce product data), `AI model` (used only to fill gaps, only where the owner allows it), `OpenStreetMap`
(only where the website said nothing; © OpenStreetMap contributors, ODbL), `business owner` (entered or confirmed by the
verified owner; wins over everything else).

## Freshness

Every website is read again about every 7 days; owners can refresh once an hour. `lastChecked`
is when the website was read, `lastChanged` when the published facts last changed. Inactive listings (website down for
several checks, shop locked or empty, parked domain) leave search results but still answer by slug with
`directory.status: "inactive"` and the reason.

## Being a good client

Send a User-Agent with a contact URL or email (`MyAgent/1.0 (+https://example.com/bot)`) and the limit rises from 600
to 1,500 requests a minute. Honour `Cache-Control` and send `If-None-Match` with the `ETag` you got. Use `/api/v1/new`,
`/feed.xml` and `/sitemap.xml` to learn what changed instead of re-reading everything. Cite the card you used.
