> ## 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.

# Trips

> Read the trips a person took, as cities and days, without ever learning where they live.

A travel app can start from the trips a person already took. PoolKit builds them on the device from where photos were taken and gives you cities and days, nothing finer.

## Ask for places visited

Trips need their own category, `.placesVisited`. No default grant includes it and `DataCategory.things` does not either, so a person always sees it named.

```swift theme={null}
let grant = try await pool.authorization.requestAccess(
    AccessRequest(
        data: [.placesVisited, .places],
        operations: [.query],
        purpose: "Show the trips you took and the places you saved for them"
    )
)
```

Add `.places` if you also want the places the person saved before each trip.

## Read the trips

```swift theme={null}
let result = try await pool.context.trips(using: grant)

guard result.home == .determined else { return }

for trip in result.trips {
    print(trip.firstDay, trip.lastDay, trip.cities.map(\.name))
}
```

| Field | Meaning |
| - | - |
| `trips` | Newest first, 50 by default. Pass `limit:` for another number. |
| `cities` | The cities of one trip, most days first, each with `name`, `countryCode`, `country` and `days` |
| `firstDay`, `lastDay`, `days` | Days as `yyyy-MM-dd` in the device's calendar. Never a time of day. |
| `assetIDs` | Up to 20 photos from the trip, to show with [evidence](https://docs.pool.day/evidence.md) |
| `savedPlaceIDs` | Places the person saved before the trip in a city they then visited. Empty without `.places`. |
| `locatedPhotos` | How many photos with a known city the grant covers |
| `coverage`, `asOf` | How much of the library was read, and when |

A grant without `.placesVisited` makes `trips` fail with `PoolError.invalidRequest`.

## Home stays out

PoolKit works out where home is on the device, and uses it only to leave it out.

* The home city never appears in a trip, and neither does any city within 75 km of it.
* A second place the person is at almost as often, such as work or a second home, is left out the same way.
* `home` tells you whether that worked. It is `.determined`, `.notEnoughLocatedPhotos` (fewer than 30 photos or 10 days with a location) or `.ambiguous` (two places are too close to call). In the last two cases `trips` is empty, because a trip list that might contain home is worse than none.
* `home` never says which city home is.

## What PoolKit keeps

* Under `.placesVisited`, only the nearest city of a photo is stored. Coordinates are read once and never kept.
* Cities come from a table inside PoolKit. No photo's location is sent to a geocoding service, Apple's included. The `.locations` category changes both, for the photos it covers: see [Places and visits](https://docs.pool.day/places.md).
* Screenshots and photos without a location never count as a visit.

> [!NOTE]
>
> If your app sends trips to your server, you are collecting coarse location. Declare it in your own privacy manifest and App Store privacy details. PoolKit's own manifest does not change, because PoolKit sends nothing.

## Attribution

PoolKit includes data from [GeoNames](https://www.geonames.org), licensed under CC BY 4.0, and a SentencePiece build licensed under MIT. Keep this line in your app's acknowledgements.


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