# Local Source Full Agent Documentation

Local Source exposes local business profile data to AI agents, coding agents, GTM workflows, and application developers.

## What This Product Does

Local Source lets agents and applications query a stored, normalized dataset of US local business profiles. Supported access paths are:

- Hosted MCP over HTTP at https://staging.getlocalsource.com/api/mcp
- REST API endpoints under https://staging.getlocalsource.com/api/v1
- Connect Console at https://staging.getlocalsource.com/connect for creating/revoking keys and copying agent setup prompts
- Agent device-code auth guide at https://staging.getlocalsource.com/auth.md

## What This Product Does Not Do In MVP

Do not use customer-facing REST or MCP tools to:

- Start scraper/provider jobs
- Trigger custom refreshes
- Crawl business websites
- Extract emails
- Extract owner names
- Extract direct/mobile phones beyond listing-derived data
- Classify businesses with AI
- Access raw provider payloads

Those are out of MVP customer scope unless a future contract explicitly adds them.

## Authentication

REST and MCP calls use:

```text
Authorization: Bearer <connection_key>
```

The Connect Console can create, store locally, clear locally, and revoke self-service keys. Environment/static development keys cannot be revoked through the Connect Console.

Agent-led setup should use https://staging.getlocalsource.com/auth.md. The device-code flow is:

1. POST https://staging.getlocalsource.com/api/auth/cli/initiate to receive deviceCode, userCode, browserUrl, expiresAt, and interval.
2. Ask the user to open browserUrl and authorize.
3. Poll GET https://staging.getlocalsource.com/api/auth/cli/poll with Authorization: Bearer <deviceCode> no faster than interval seconds.
4. Persist the one-time apiKey response as LOCAL_SOURCE_API_KEY immediately.

## Hosted MCP

Endpoint:

```text
https://staging.getlocalsource.com/api/mcp
```

Expected tools:

- `search_places`
- `get_place`
- `count_places`
- `list_categories`
- `get_usage`

Recommended first verification prompt:

```text
Use Local Source. Call list_categories with query="dent" and limit=5.
If that works, say: "Local Source is connected."
```

## REST Endpoints

### POST /api/v1/places/search

Search stored local business profiles.

Common body fields:

```json
{
  "query": "optional keyword",
  "categories": ["dentist"],
  "states": ["MI"],
  "cities": ["Detroit"],
  "postal_codes": ["48201"],
  "require_website": true,
  "require_phone": false,
  "min_rating": 4,
  "min_review_count": 10,
  "limit": 10
}
```

Use low limits while exploring. Maximum limits may vary by plan and surface.

Example:

```bash
curl -s https://staging.getlocalsource.com/api/v1/places/search \
  -H "Authorization: Bearer $LOCAL_SOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"categories":["dentist"],"states":["MI"],"limit":5}'
```

### GET /api/v1/categories

List or search supported public categories.

### GET /api/v1/usage

Return current usage for the authenticated account/key.

## Response Expectations

Business records may include:

- public place id
- name
- address/city/state/postal_code
- phone when listing-derived and present
- website_url when listing-derived and present
- latitude/longitude when available
- rating and review_count when available
- categories
- first_seen_at and last_seen_at
- provenance/freshness summary

Agents should preserve freshness/provenance fields in important outputs and should not present stale or incomplete records as verified current facts.

## Safe Agent Behavior

- Ask for narrower geography/category when a request is too broad.
- Page through results deliberately instead of asking for huge limits.
- Do not claim email, owner, website-crawled, or AI-derived fields exist unless returned by the API.
- If a rate limit is returned, wait according to retry_after_seconds or report that value to the user.
- For outbound or marketing use, remind the user they are responsible for applicable laws and platform rules.

## Product Structure

- Marketing site should explain outcomes and link users to the Connect Console.
- Product app owns /connect, REST, MCP, key lifecycle, usage, and these agent-readable docs.
- Stable future endpoint targets should be https://api.agentmapdata.com/v1 and https://mcp.agentmapdata.com/mcp, even if current routes are app-hosted.