# HomeCompass — import instructions for an AI assistant

You are importing someone's list of places to live into HomeCompass, a private
tool for comparing homes. Work from whatever they give you: a spreadsheet, a
doc, saved listings, screenshots, or links.

## Authentication

Every request needs the owner's API token in a header:

    Authorization: Bearer THEIR_TOKEN

They copy the token from the app (Import → Copy token). It stays the same until
they rotate it. If a request returns 401, stop and ask them for a fresh token —
do not retry with guesses.

## Endpoints

Base URL: https://apartmentcompare.pages.dev

    GET    /api/v1/places
           List the places already in the workspace. Do this first to avoid duplicates.

    POST   /api/v1/places
           Add places. Body: {"places": [ ... ]} — up to 50 at a time.

    PATCH  /api/v1/places/{id}
           Update one place. Send only the fields that change.

    DELETE /api/v1/places/{id}
           Remove one place.

## A place looks like this

```json
{
  "name": "Tower 12",
  "address": "2015 2nd Ave, Seattle, WA 98121",
  "type": "apartment | townhome | house | condo",
  "status": "touring | undecided | not-touring",
  "neighborhood": "Belltown",
  "stories": 34,
  "beds": 2,
  "rent": {
    "low": 4500,
    "high": 5000
  },
  "sqft": {
    "low": 1100,
    "high": 1150
  },
  "balcony": "yes | some | no | unknown",
  "ac": "yes | no | unknown",
  "viewTypes": [
    "bay",
    "mountains",
    "lake",
    "river",
    "park",
    "city",
    "needle"
  ],
  "ratings": {
    "views": 5,
    "gym": 4,
    "reviews": 5,
    "location": 5
  },
  "concession": "2 months free",
  "notes": "Anything the person wrote about it — kept verbatim.",
  "url": "https://example.com/listing"
}
```

Only `name` and `address` are required. Send a full street address including
the city and state — the server geocodes it, and a vague address lands in the
wrong spot or not at all. Everything else is optional; omit what you don't know
rather than guessing.

## How to do the import

1. `GET /api/v1/places` first, so you update existing entries instead of
   creating duplicates. A place with the same address in the same group is
   treated as an update.
2. Convert their list. Keep their own words in `notes` — the app shows that
   text as their notes and they can edit it later.
3. `POST /api/v1/places` with `{"places": [...]}`, at most 50 per call.
4. Report back: how many were added, how many updated, and anything you could
   not geocode (the response lists those under `problems`).

## Rules

- Do not invent rent, square footage, ratings or review scores. Leave a field
  out if the source doesn't state it.
- `ratings` are the owner's 1–5 opinions, not review-site scores. Only fill
  them in if the source clearly expresses an opinion.
- `status` defaults to `undecided`. Only set `touring` or `not-touring` if
  the source says so.
- Facade directions, footprints and commute times are computed by the app. Do
  not try to supply them.
- One address per place. A building with several units of interest is one place;
  the owner tracks the individual unit numbers in the app.

## Example

```bash
curl -X POST https://apartmentcompare.pages.dev/api/v1/places \
  -H "Authorization: Bearer THEIR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"places":[{"name":"Tower 12","address":"2015 2nd Ave, Seattle, WA 98121","rent":{"low":4500},"sqft":{"low":1100},"notes":"Great gym, 2 months free."}]}'
```