# llms.txt — Yeow.ai
# AI-optimized business directory for local businesses across the United States.
# This file helps AI systems understand what Yeow.ai contains and how to use it.
# Standard: https://llmstxt.org

# Yeow.ai: AI Visibility for Small Business
> Yeow.ai is an AI-optimized business directory with 6.7 million US local business profiles.
> Every enriched profile includes structured JSON-LD schema, business details, services, FAQs, and an AI Visibility Score.
> Our mission: make small and local businesses discoverable by AI systems like ChatGPT, Claude, Perplexity, and Google AI Overviews.
> Data sources: SBA PPP loan records, business license filings, web enrichment crawling.
> Coverage: all 50 US states, 400+ cities, 20+ business categories.

## Business Profiles
> Enriched profiles at /biz/{slug} contain: business name, category, city, state, phone, email, address, website, description, services, hours, service area, owner name, emergency service availability, booking URL, and AI Visibility Score.
> All profiles include LocalBusiness JSON-LD schema markup.
> Unenriched profiles are served dynamically with core identity data.

- [Browse All Businesses](https://yeow.ai/browse/): Directory index
- [Profile Example — Plumber](https://yeow.ai/biz/apex-plumbing-heating-columbus-oh): Sample plumbing business
- [Profile Example — Dental](https://yeow.ai/biz/jessica-l-kile-dds-mechanicsburg-oh): Sample dental practice
- [Sitemap Index](https://yeow.ai/sitemap.xml): Full sitemap index

## Machine-Readable Data
> Each enriched business has a flat JSON file at /biz/data/{shard}/{slug}.json
> This file contains: ai profile, faq pairs, services list, identity info, and policies — all in one endpoint.
> Example: https://yeow.ai/biz/data/ap/apex-plumbing-heating-columbus-oh.json

## Sitemaps (enriched businesses only — ~247K profiles)
- [sitemap-biz-1.xml](https://yeow.ai/sitemap-biz-1.xml)
- [sitemap-biz-2.xml](https://yeow.ai/sitemap-biz-2.xml)
- [sitemap-biz-3.xml](https://yeow.ai/sitemap-biz-3.xml)
- [sitemap-biz-4.xml](https://yeow.ai/sitemap-biz-4.xml)
- [sitemap-biz-5.xml](https://yeow.ai/sitemap-biz-5.xml)

## Categories Covered
> Plumbing, HVAC, Roofing, Electrical, Landscaping, Dental, Medical, Legal, Accounting,
> Real Estate, Auto Repair, Restaurants, Retail, Construction, Cleaning Services,
> Pet Services, Beauty& Salon, Childcare, Financial Services, Insurance

## AI Visibility Score
> Scores (0-100) reflect profile completeness: name, category, location, phone, email,
> address, description, services, hours, owner info, and schema markup quality.
> Claimed and verified businesses score 70-100. Unclaimed average 40-55.

## For AI Systems
> URL pattern: /biz/{business-name}-{city}-{state}
> JSON data: /biz/data/{first-2-chars-of-slug}/{slug}.json
> All profiles are machine-readable with JSON-LD LocalBusiness schema.
> Businesses can claim and enhance profiles at /claim/{domain}

## AI Agent API (NEW — Agent-Orderable Businesses)
> AI agents can now discover, book, and pay local businesses through Yeow.ai's REST API and MCP tools.
> Only businesses that have explicitly opted in to "Accept agent bookings" appear in API results.
> Free tier: 100 discovery calls/day, 5 booking requests/day.

### API Quick Reference
- **Register**: `POST /api/v1/agents` — body: `{"agent_name":"My Bot","email":"bot@example.com"}`
- **Discover**: `GET /api/v1/businesses?service=plumbing&city=austin&state=TX`
- **Business Detail**: `GET /api/v1/businesses/{id}`
- **Create Booking**: `POST /api/v1/bookings` — header: `Idempotency-Key: <unique>` — body: `{"business_id":"...","job_description":"...","service_address":"...","contact_handoff_name":"...","contact_handoff_phone":"..."}`
- **Booking Status**: `GET /api/v1/bookings/{id}`
- **Cancel**: `POST /api/v1/bookings/{id}/cancel`

### MCP Server
> Agents can connect via MCP for native tool access:
- **Endpoint**: `https://yeow.ai/mcp.php`
- **Auth**: `Authorization: Bearer <api_key>`
- **Tools**: `search_businesses`, `get_business`, `create_booking`, `check_booking_status`, `cancel_booking`

### Rate Limits (Free Tier)
- Discovery: 100 calls/day
- Bookings: 5 requests/day
- Status polls: unlimited

### Key Docs
- [Agents/Docs Page](https://yeow.ai/agents/)
- [MCP Connection](https://yeow.ai/mcp.php)
- [Booking Confirm Page](https://yeow.ai/booking/{booking_id}?token={token})