> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pool.day/llms.txt
> Use this file to discover all available pages before exploring further.

# Places and visits

> Know where photos were taken, down to the neighbourhood and the venue, without ever learning where the person lives.

A photo taken at a museum in Lisbon on a Saturday morning says a lot: the city, the neighbourhood, the kind of place, who was there. PoolKit reads that on the device and gives it to you per photo, grouped into visits, and lets search understand place words.

## Ask for locations

Exact places need their own category, `.locations`. No other category implies it, no default grant includes it, and the person always sees it named. Ask for it on its own, in plain words.

```swift theme={null}
let grant = try await pool.authorization.requestAccess(
    AccessRequest(
        sources: [.photos],
        data: [.locations],
        operations: [.search],
        purpose: "Find the photos from the places you've been"
    )
)
```

If city and country are enough, ask for `.placesVisited` instead. It powers [Trips](https://docs.pool.day/trips.md) and never gives coordinates, neighbourhoods or visits.

| | `.placesVisited` | `.locations` |
| - | - | - |
| City and country | Yes | Yes |
| Neighbourhood, metro area, coordinates | No | Yes |
| Visits, venues and their context | No | Yes |
| Time zone | Yes | Yes |
| Search by city and country | Yes | Yes |
| Search by neighbourhood, venue and kind of venue | No | Yes |

## Read a photo's place

Every hit from `search` and `similar` carries `details`. Under `.locations` it has `location`, `visit` and `timeZone`.

```swift theme={null}
let result = try await pool.context.search("museum in Lisbon", using: grant)

for hit in result.hits {
    if let location = hit.details.location {
        print(location.description ?? "")        // "Chiado, Lisbon, Portugal"
    }
    if let visit = hit.details.visit, let venue = visit.venue {
        print(venue.name, venue.category ?? "", venue.confidence)
    }
}
```

| On `details.location` | Meaning |
| - | - |
| `neighborhood` | The neighbourhood or district, such as `Chiado`. Under `.locations` only. |
| `city`, `country`, `countryCode` | The city, the country and its ISO 3166 code. |
| `metro` | The wider area, such as `Greater London`. Under `.locations` only. |
| `latitude`, `longitude` | Where the photo was taken. Under `.locations` only. |
| `description` | A short line for display, such as `Chiado, Lisbon, Portugal`. |

## Visits

A visit is a run of photos and videos close in time and place: each one within 90 minutes of the previous and within 400 metres of the visit's centre. Screenshots never count.

| On `details.visit` | Meaning |
| - | - |
| `id`, `start`, `end`, `photoCount` | The visit and how many photos and videos it holds. |
| `location` | The visit's place, with the same fields as above. |
| `venue` | The nearest venue Maps knows within the visit, with its `name`, a plain `category` such as `national park` or `ramen restaurant`, and a `confidence` from 0 to 1. Missing when nothing is close enough. |
| `context` | `awayFromHome`, `withPeople`, `peopleCount` (the most faces in one photo, counted and never recognized), `partOfDay`, `weekend` and `selfie`. |

A capture at a venue also gains an [activity](https://docs.pool.day/interests.md) with source `venue`, so interests learn from where people go, not only what they photograph.

## Search by place

Place words are a third list that search ranks next to the words on screen and what the image shows. "Lisbon", "Chiado", "museum" and "ramen" all work, and so do mixes such as "sunset in Lisbon".

* Hits that matched a place carry the reason `.place`, the words that named it in `placeMatches`, and `placeSimilarity`, the share of the query's words that named the place.
* `searchPlan.operation` is `location` when every word named a place, and `retrievalIntent` says `place`, `placeType` (a kind of venue, such as "museum") or `contentAndPlace` when the query mixed both. See [Search and browse](https://docs.pool.day/search.md).
* Under `.placesVisited`, only city and country words match.

## Home stays out

Places appear once PoolKit has seen enough located photos to know where home is: 30 photos on 10 different days, as for [Trips](https://docs.pool.day/trips.md). Until then nothing is shown at all, because any place could be home.

After that, captures near home carry no location, no visit and no venue, and never match a place search. PoolKit never says where home is.

## Where the names come from

* Apple's geocoder names the neighbourhood, city, metro area, country and time zone. Apple Maps finds the venue. Both see the coordinates of the place they name; Pool's service never does.
* Each area is looked up once and kept on the device: names about once per square kilometre, venues about once per 200 metres.
* Lookups are slow on purpose: at most one every 1.5 seconds and 60 per indexing run, and never on a cellular or other metered connection. The next run carries on.
* Offline, the city comes from a table inside PoolKit (cities of 15,000 people or more, within 75 km). Apple's names replace it later.

## Taking it back

When no active grant includes `.locations` any more, the next indexing run deletes every coordinate, visit, venue and place name. Deleting a photo deletes its visit when no other photo is left in it, and any place name nothing uses any more.

If your app sends places to your server, you are collecting location. Declare precise or coarse location in your own privacy manifest and App Store privacy details, whichever you send. PoolKit's own manifest does not change, because PoolKit sends no location to Pool.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.