Planning routes#

Transit Directions#

Transit Directions

Get transit routes between two locations using planTransitRoutes().

In the happy case, you will receive up to 5 transit Routes. If both endpoints are not in the same Citymapper coverage area, you'll receive a failure result, and no billable session will be recorded.

Swift

CitymapperDirections.shared.planTransitRoutes(
    start: CLLocationCoordinate(latitude: 51.504175, longitude: -0.105884),
    end: CLLocationCoordinate(latitude: 51.498255, longitude: -0.098251)) { (result) in
    switch result {
        case .failure(let error):
            print(error)
        case .success(let data):
            guard let route = data.routes.first else {
                return
            }
            // Display the Route
    }
}

Kotlin

//suspend function
coroutineScope.launch {
    val result = CitymapperDirections.getInstance(context).planTransitRoutes(
        start = Coords(51.504175, -0.105884),
        end = Coords(51.498255, -0.098251)
    ).execute()
    when (result) {
        is ApiResult.Failure.NetworkFailure -> {
            Log.e(TAG, "ApiResult Network failure", result.error)
        }
        is ApiResult.Failure.UnknownFailure -> {
            Log.e(TAG, "ApiResult Unknown failure", result.error)
        }
        is ApiResult.Failure.HttpFailure -> {
            Log.e(TAG, "HttpFailure ${result.code} - ${result.error}")
        }
        is ApiResult.Success -> {
            val route = result.data.routes.first()
            // Display the Route
        }
    }
}

//callback
CitymapperDirections.getInstance(context).planTransitRoutes(
    start = Coords(51.504175, -0.105884),
    end = Coords(51.498255, -0.098251)
).executeAsync { result ->
    when (result) {
        is ApiResult.Failure.NetworkFailure -> {
            Log.e(TAG, "ApiResult Network failure", result.error)
        }
        is ApiResult.Failure.UnknownFailure -> {
            Log.e(TAG, "ApiResult Unknown failure", result.error)
        }
        is ApiResult.Failure.HttpFailure -> {
            Log.e(TAG, "HttpFailure ${result.code} - ${result.error}")
        }
        is ApiResult.Success -> {
            val route = result.data.routes.first()
            // Display the Route
        }
    }
}

Java

CitymapperDirections.getInstance(context).planTransitRoutes(
        new Coords(51.504175, -0.105884),
        new Coords(51.498255, -0.098251)
).executeAsync(result -> {
    if (result.isSuccess()) {
        DirectionsResults results = result.getSuccessData();
        Route route = results.getRoutes().get(0);
        // Display the Route
    } else {
        Log.e("DEBUG", "ApiResult failure", result.getFailureException());
    }
});

Bike Directions#

Bike Directions

You can get a bike route using planBikeRoutes(). This route is for riding the bike the entire way between the given start & end points.

Swift

import CitymapperNavigation

CitymapperDirections.shared.planBikeRoutes(
    start: CLLocationCoordinate(latitude: 51.504175, longitude: -0.105884),
    end: CLLocationCoordinate(latitude: 51.498255, longitude: -0.098251),
    profiles: [.quiet, .regular, .fast]) { (result) in
    switch result {
        case .failure(let error):
            print(error)
        case .success(let data):
            guard let route = data.routes.first else {
                return
            }
            // Display the Route
    }
}

Kotlin

//suspend function
coroutineScope.launch {
    val result = CitymapperDirections.getInstance(context).planBikeRoutes(
        start = Coords(51.504175, -0.105884),
        end = Coords(51.498255, -0.098251),
        profiles = listOf(Profile.Quiet, Profile.Regular, Profile.Fast)
    ).execute()
    when (result) {
        is ApiResult.Failure.NetworkFailure -> {
            Log.e(TAG, "ApiResult Network failure", result.error)
        }
        is ApiResult.Failure.UnknownFailure -> {
            Log.e(TAG, "ApiResult Unknown failure", result.error)
        }
        is ApiResult.Failure.HttpFailure -> {
            Log.e(TAG, "HttpFailure ${result.code} - ${result.error}")
        }
        is ApiResult.Success -> {
            val route = result.data.routes.first()
            // Display the Route
        }
    }
}

//callback
CitymapperDirections.getInstance(context).planBikeRoutes(
    start = Coords(51.504175, -0.105884),
    end = Coords(51.498255, -0.098251),
    profiles = listOf(Profile.Quiet, Profile.Regular, Profile.Fast)
).executeAsync { result ->
    when (result) {
        is ApiResult.Failure.NetworkFailure -> {
            Log.e(TAG, "ApiResult Network failure", result.error)
        }
        is ApiResult.Failure.UnknownFailure -> {
            Log.e(TAG, "ApiResult Unknown failure", result.error)
        }
        is ApiResult.Failure.HttpFailure -> {
            Log.e(TAG, "HttpFailure ${result.code} - ${result.error}")
        }
        is ApiResult.Success -> {
            val route = result.data.routes.first()
            // Display the Route
        }
    }
}

Java

CitymapperDirections.getInstance(context).planBikeRoutes(
        new Coords(51.504175, -0.105884),
        new Coords(51.498255, -0.098251),
        Arrays.asList(Profile.Quiet, Profile.Regular, Profile.Fast)
).executeAsync(result -> {
    if (result.isSuccess()) {
        DirectionsResults results = result.getSuccessData();
        Route route = results.getRoutes().get(0);
        // Display the Route
    } else {
        Log.e("DEBUG", "ApiResult failure", result.getFailureException());
    }
});

Profiles#

The Citymapper SDK currently supports getting up to 3 different bicycle Routes. (In practice, the results may not actually be different from each other if there's only a few optimal paths for your start & end point.) If the profiles parameter is omitted, the regular profile is used.

profile	description
`quiet`	Attempts to use roads with less traffic
`regular`	The default profile, balances traffic with directness
`fast`	Attempts to find the shortest sensible Route

E-Scooter Directions#

E-Scooter Directions

You can get an e-scooter route using planScooterRoute(). This route is for riding the scooter the entire way between the given start & end points.

Swift

CitymapperDirections.shared.planScooterRoute(
    start: CLLocationCoordinate(latitude: 51.504175, longitude: -0.105884),
    end: CLLocationCoordinate(latitude: 51.498255, longitude: -0.098251)) { (result) in
    switch result {
        case .failure(let error):
            print(error)
        case .success(let data):
            guard let route = data.routes.first else {
                return
            }
            // Display the Route
    }
}

Kotlin

//suspend function
coroutineScope.launch {
    val result = CitymapperDirections.getInstance(context).planScooterRoute(
        start = Coords(51.504175, -0.105884),
        end = Coords(51.498255, -0.098251)
    ).execute()
    when (result) {
        is ApiResult.Failure.NetworkFailure -> {
            Log.e(TAG, "ApiResult Network failure", result.error)
        }
        is ApiResult.Failure.UnknownFailure -> {
            Log.e(TAG, "ApiResult Unknown failure", result.error)
        }
        is ApiResult.Failure.HttpFailure -> {
            Log.e(TAG, "HttpFailure ${result.code} - ${result.error}")
        }
        is ApiResult.Success -> {
            val route = result.data.routes.first()
            // Display the Route
        }
    }
}

//callback
CitymapperDirections.getInstance(context).planScooterRoute(
    start = Coords(51.504175, -0.105884),
    end = Coords(51.498255, -0.098251)
).executeAsync { result ->
    when (result) {
        is ApiResult.Failure.NetworkFailure -> {
            Log.e(TAG, "ApiResult Network failure", result.error)
        }
        is ApiResult.Failure.UnknownFailure -> {
            Log.e(TAG, "ApiResult Unknown failure", result.error)
        }
        is ApiResult.Failure.HttpFailure -> {
            Log.e(TAG, "HttpFailure ${result.code} - ${result.error}")
        }
        is ApiResult.Success -> {
            val route = result.data.routes.first()
            // Display the Route
        }
    }
}

Java

CitymapperDirections.getInstance(context).planScooterRoute(
        new Coords(51.504175, -0.105884),
        new Coords(51.498255, -0.098251)
).executeAsync(result -> {
    if (result.isSuccess()) {
        DirectionsResults results = result.getSuccessData();
        Route route = results.getRoutes().get(0);
        // Display the Route
    } else {
        Log.e("DEBUG", "ApiResult failure", result.getFailureException());
    }
});

Walk Directions#

Walk Directions

You can get an walk route using planWalkRoutes().

Swift

CitymapperDirections.shared.planWalkRoutes(
    start: CLLocationCoordinate(latitude: 51.504175, longitude: -0.105884),
    end: CLLocationCoordinate(latitude: 51.498255, longitude: -0.098251),
    profiles: [.fast, .mainRoads]) { (result) in
    switch result {
        case .failure(let error):
            print(error)
        case .success(let data):
            guard let route = data.routes.first else {
                return
            }
            // Display the Route
    }
}

Kotlin

//suspend function
coroutineScope.launch {
    val result = CitymapperDirections.getInstance(context).planWalkRoutes(
        start = Coords(51.504175, -0.105884),
        end = Coords(51.498255, -0.098251),
        profiles = listOf(Profile.Fast, Profile.MainRoads)
    ).execute()
    when (result) {
        is ApiResult.Failure -> {
            Log.e("DEBUG", "ApiResult failure", result.exception)
        }
        is ApiResult.Success -> {
            val route = result.data.routes.first()
            // Display the Route
        }
    }
}

//callback
CitymapperDirections.getInstance(context).planWalkRoutes(
    start = Coords(51.504175, -0.105884),
    end = Coords(51.498255, -0.098251)
).executeAsync { result ->
    when (result) {
        is ApiResult.Failure -> {
            Log.e("DEBUG", "ApiResult failure", result.exception)
        }
        is ApiResult.Success -> {
            val route = result.data.routes.first()
            // Display the Route
        }
    }
}

Java

CitymapperDirections.getInstance(this).planWalkRoutes(
        new Coords(51.504175, -0.105884),
        new Coords(51.498255, -0.098251)
).executeAsync(result -> {
    if (result.isSuccess()) {
        DirectionsResults results = result.getSuccessData();
        Route route = results.getRoutes().get(0);
        // Display the Route
    } else {
        Log.e("DEBUG", "ApiResult failure", result.getFailureException());
    }
});

Set Walk Route Profiles#

The Citymapper SDK currently supports getting up to 2 different walk Routes. (In practice, the results may not actually be different from each other if there's only a few optimal paths for your start & end point.) If the profiles parameter is omitted, the fast profile is used.

profile	description
`fast`	The default profile, attempt to find the fastest route for given A-B
`main_roads`	Attemps to find the main roads even it could be longer