# Citymapper

Canonical HTML: https://p-hatan.com/deeplink-x/apps/citymapper/

DeeplinkX 1.5.8.

## Platforms and setup

Native platforms: **ios, android**.

- view opens directions to a point from the current location; it does not promise a marker-only map.
- Coordinate routes only; no text-only directions or travel-mode selector is exposed.
- arriveBy preserves the supplied instant and serializes UTC; device-local time is not inferred from destination.

## Public actions

### Citymapper.open


```dart
factory Citymapper.open({final bool fallbackToStore = false})
```

Launch with `DeeplinkX.launchApp`. Native platforms: **ios, android**. Action web fallback: **available**. Store-fallback flag: **supported; opt in explicitly**.

| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `fallbackToStore` | `bool` | No | `false` |

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/downloadable_apps/citymapper.dart#L9)

### Citymapper.view


```dart
static CitymapperViewAction view({ required final Coordinate coordinate, final String? title, final bool fallbackToStore = false, })
```

Launch with `DeeplinkX.launchAction`. Native platforms: **ios, android**. Action web fallback: **available**. Store-fallback flag: **supported; opt in explicitly**.

| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `coordinate` | `Coordinate` | Yes | — |
| `title` | `String?` | No | — |
| `fallbackToStore` | `bool` | No | `false` |

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/downloadable_apps/citymapper.dart#L15)

### Citymapper.directionsWithCoords


```dart
static CitymapperDirectionsWithCoordsAction directionsWithCoords({ required final Coordinate destination, final Coordinate? origin, final String? destinationTitle, final String? originTitle, final String? destinationAddress, final String? originAddress, final DateTime? arriveBy, final bool fallbackToStore = false, })
```

Launch with `DeeplinkX.launchAction`. Native platforms: **ios, android**. Action web fallback: **available**. Store-fallback flag: **supported; opt in explicitly**.

| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `destination` | `Coordinate` | Yes | — |
| `origin` | `Coordinate?` | No | — |
| `destinationTitle` | `String?` | No | — |
| `originTitle` | `String?` | No | — |
| `destinationAddress` | `String?` | No | — |
| `originAddress` | `String?` | No | — |
| `arriveBy` | `DateTime?` | No | — |
| `fallbackToStore` | `bool` | No | `false` |

[Exact source](https://github.com/DeepLinkX/DeeplinkX/blob/00d9d2c7c1affe4e2ee459a01afeba82a1480eac/lib/src/apps/downloadable_apps/citymapper.dart#L31)


## Provider setup and examples
DeeplinkX supports the Citymapper custom URI scheme on iOS and Android for opening the app and building route requests.

## First-party References

- [Citymapper directions-link guide](https://citymapper.com/news/2386/launch-citymapper-for-directions)
- [Citymapper native/web links and arrival-time documentation](https://citymapper.com/news/895/launching-citymapper-from-apps-and-from-the-web)
- [Google Play listing](https://play.google.com/store/apps/details?id=com.citymapper.app.release)
- [Apple App Store listing](https://apps.apple.com/us/app/citymapper-all-live-transit/id469463298)

Citymapper opens coordinate-based directions from the current location or a supplied origin. Configure the package and scheme visibility below.

## Available Actions

### Launch Citymapper

```dart
final deeplinkX = DeeplinkX();
await deeplinkX.launchApp(Citymapper.open());
```

### View Map

The verified Citymapper contract describes directions rather than a marker-only map. `Citymapper.view` implements the shared `MapViewAction` interface by opening directions to the coordinate from the user's current location. It does not promise a standalone marker view.

```dart
await deeplinkX.launchAction(
  Citymapper.view(
    coordinate: const Coordinate(latitude: 51.503399, longitude: -0.119519),
    title: 'London Eye',
  ),
);
```

### Directions With Coordinates

```dart
await deeplinkX.launchAction(
  Citymapper.directionsWithCoords(
    origin: const Coordinate(latitude: 51.500729, longitude: -0.124625),
    destination: const Coordinate(latitude: 51.503399, longitude: -0.119519),
    originTitle: 'Westminster',
    destinationTitle: 'London Eye',
    arriveBy: DateTime.utc(2026, 12, 2, 15, 30),
  ),
);
```

Citymapper route URLs are coordinate based, so DeeplinkX does not expose a text-only `directions` action for this app.

Omit `origin` to request directions from the current location. Without an origin, `originTitle` and `originAddress` are ignored and all `start*` parameters are omitted. Destination titles and addresses are optional display information, not substitutes for coordinates.

`arriveBy` is optional. DeeplinkX serializes it as UTC ISO-8601 with a `Z` suffix while preserving the instant. A local `DateTime` is interpreted in the caller device's local time zone—not inferred from the destination; use `DateTime.utc` or an offset-aware parsed value to specify an unambiguous instant. Both native and web links receive the same parameters. No travel-mode selector is exposed.

## Platform Configuration

### iOS

Add the Citymapper scheme to the `LSApplicationQueriesSchemes` array in `ios/Runner/Info.plist`:

```xml
<string>citymapper</string>
```

### Android

Allow querying the package in `android/app/src/main/AndroidManifest.xml`:

```xml
<queries>
  <package android:name="com.citymapper.app.release" />
</queries>
```

Navigation intents use `action_view`, package `com.citymapper.app.release`, and `FLAG_ACTIVITY_NEW_TASK` (`0x10000000`). The existing platform adapter may retry without package targeting when resolution fails; this provider does not change that adapter or guarantee strict targeting in every failure case.

## URI Formats

- Directions destination: `citymapper://directions?endcoord={latitude},{longitude}&endname={title?}`
- Directions with origin: `citymapper://directions?startcoord={originLatitude},{originLongitude}&startname={originTitle?}&startaddress={originAddress?}&endcoord={destinationLatitude},{destinationLongitude}&endname={destinationTitle?}&endaddress={destinationAddress?}&arriveby={utcIso8601?}`
- Web fallback: `https://citymapper.com/directions?...`

Optional parameters are omitted when `null`; supplied strings are URL-encoded using Dart's URI query construction. Empty strings remain supplied values.

## Fallback Behavior

1. DeeplinkX opens the native app when installed.
2. If the app is missing and `fallbackToStore` is `true`, we redirect to the appropriate store listing.
3. Otherwise the action falls back to `https://citymapper.com/directions` with the same route parameters.
4. Set `disableFallback: true` when calling `launchAction` to skip both store and web fallbacks.

### Fallback Support Matrix

| Action                       | Store Fallback | Web Fallback |
| ---------------------------- | -------------- | ------------ |
| Open app                     | ✔️              | ✔️ (website) |
| View map                     | ✔️              | ✔️           |
| Directions with coordinates  | ✔️              | ✔️           |