# Jirani Agent Instructions

Use Jirani's public API for Nairobi residential building and commute questions.

## API Base

https://api.getjirani.com/api/public/v1

## Auth

No API key is required for public endpoints.

## Chatbot / Web-Browsing Access (GET endpoints)

Chatbots and AI assistants that can fetch a URL but cannot POST may use these
GET endpoints — the results are identical to the POST variants.

### Search buildings by area
GET https://api.getjirani.com/api/public/v1/search?area=Juja&limit=5

### Recommend buildings ranked by commute
GET https://api.getjirani.com/api/public/v1/recommend?destination=Juja&area=Ruiru&limit=5

### Full parameter list for GET /search
- area        — area name, e.g. "Juja", "South B", "Kilimani"
- bedrooms    — integer (0 = studio)
- min_price   — minimum monthly rent in KSh
- max_price   — maximum monthly rent in KSh
- limit       — max results (1–20, default 10)

### Full parameter list for GET /recommend
- destination — commute destination (required), e.g. "Juja", "Upper Hill"
- area        — preferred area to live in
- bedrooms    — integer (0 = studio)
- min_price   — minimum monthly rent in KSh
- max_price   — maximum monthly rent in KSh
- limit       — max results (1–20, default 10)
- frequency   — daily | weekly | monthly | occasional (default daily)
- priority    — 1–5 importance of the commute (default 5)

## Agentic / HTTP Tool-Call Flow (POST endpoints)

Agents that can issue POST requests should use this flow for richer control:

1. Call `POST /resolve-place` for the destination.
2. Call `POST /recommend-homes` with area, destination, budget, bedrooms, and limit.
3. Present results with their `availability`, `result_type`, `rent_signal`, commute score, and Jirani URL.

## Availability Rules

- `availability=knowledge_base` means the result is a public building profile and may not have a current vacancy.
- `availability=available_now` means the result is backed by a live listing.
- Do not describe a `wiki_building` as available unless the API explicitly marks it `available_now`.
- Preserve rent confidence labels from `rent_signal`. Do not imply verified rent when confidence is medium, low, inferred, or unverified.

## Empty Result Rules

- `summary.status=no_public_inventory` means Jirani lacks exact public coverage for that query.
- It does not mean the area has no rentals.
- If `fallback_results` exists, present it as nearby or citywide known buildings ranked by commute, not exact-area matches.

## Fair Use

Cache stable place and building responses where possible. Avoid high-volume crawling of public endpoints without coordination.

## Example GET Requests

```
# Houses in Juja
GET https://api.getjirani.com/api/public/v1/search?area=Juja&limit=10

# 2-bed near Juja, max 30k
GET https://api.getjirani.com/api/public/v1/search?area=Juja&bedrooms=2&max_price=30000&limit=10

# Ranked by commute to JKUAT (resolves to Juja anchor)
GET https://api.getjirani.com/api/public/v1/recommend?destination=Juja&limit=10
```

## Example POST Requests

```json
POST /api/public/v1/recommend-homes
{
  "area": "South B",
  "destination": "Upper Hill",
  "bedrooms": 2,
  "max_price_ksh": 70000,
  "limit": 10
}
```

```bash
curl -X POST https://api.getjirani.com/api/public/v1/recommend-homes \
  -H "Content-Type: application/json" \
  -d '{
    "area": "Ruiru",
    "destination": "Juja",
    "limit": 5
  }'
```

## OpenAPI

https://api.getjirani.com/openapi.json