stplanpy.cycle module

The functions in this module are used to retrieve cycling routes from the Cycle Streets website.

stplanpy.cycle.expire_cache(expire=- 1)

Set cache expiration time

This function can be used to modify the cache expiration time. This is useful when one wants to update only part of the cache. The procedure would be to set expire to 1 (second), call the routes() function for the routes that need to be updated, and call expire_cache() again to set expire back to -1 (never expires).

Parameters

expire (int, defaults to -1) – Time after which the cache expires in seconds. Options are: -1 to never expire, 0 to disable caching, or a number. Days can be set using e.g. timedelta(days=180). Defaults to -1.

See also

routes

Examples

import pandas as pd
import geopandas as gpd
from shapely import wkt
from stplanpy import cycle

# Define two origin-destination lines
df = pd.DataFrame(
    {"geometry": [
    "LINESTRING(-11785727.431 4453819.337, -11782276.436 4448452.023)",
    "LINESTRING(-11785787.392 4450797.573, -11787086.209 4449884.472)"]})

# Convert to WTK
df["geometry"] = gpd.GeoSeries.from_wkt(df["geometry"])

# Create GeoDataFrame
gdf = gpd.GeoDataFrame(df, geometry='geometry', crs="EPSG:6933")

# Read the Cycle Streets API key
cyclestreets_key = cycle.read_key()

# Compute routes for the 1st time
gdf["geometry"] = gdf.routes(api_key=cyclestreets_key)

# Set cache expiration
cycle.expire_cache(expire=1)

# Update cache for second route
gdf = gdf.copy().iloc[[1]]
gdf["geometry"] = gdf.routes(api_key=cyclestreets_key)

# Reset cache expiration
cycle.expire_cache()
stplanpy.cycle.find_cent(fd: geopandas.geodataframe.GeoDataFrame, orig='orig_taz', dest='dest_taz')

Find centroid tazce codes

If the routes() function is not able to find a route between two locations it returns a “Point” geometry. This function can be used to find these points and writes the tazce codes of the origin and destination to screen.

Parameters

  • orig (str, defaults to "orig_taz") – Column name that contains origin tazce codes.

  • dest (str, defaults to "dest_taz") – Column name that contains destination tazce codes.

See also

routes

Examples

import pandas as pd
import geopandas as gpd
from shapely import wkt
from stplanpy import cycle

# Define two origin-destination lines
df = pd.DataFrame({
    "orig_taz" : ["73906", "00106"],
    "dest_taz" : ["00120", "04120"],
    "geometry": [
    "LINESTRING(-91785727.431 4453819.337, -11782276.436 4448452.023)",
    "LINESTRING(-11785787.392 4450797.573, -11787086.209 4449884.472)"]})

# Convert to WTK
df["geometry"] = gpd.GeoSeries.from_wkt(df["geometry"])

# Create GeoDataFrame
gdf = gpd.GeoDataFrame(df, geometry='geometry', crs="EPSG:6933")

# Read the Cycle Streets API key
cyclestreets_key = cycle.read_key()

# Compute routes
gdf["geometry"] = gdf.routes(api_key=cyclestreets_key)
gdf.find_cent()
stplanpy.cycle.read_key(key_file='cyclestreets_key.txt')

Read a Cycle Streets API key from a file.

This function reads the Cycle Streets API key from a file. The default file name is “cyclestreets_key.txt” and the key should be stored in plain text.

Parameters

key_file (str, defaults to "cyclestreets_key.txt") – Name and path of the file storing the Cycle Streets API key

Returns

Cycle Streets API key

Return type

str

See also

routes

Examples

from stplanpy import cycle

# Read the Cycle Streets API key
cyclestreets_key = cycle.read_key()
stplanpy.cycle.routes(fd: geopandas.geodataframe.GeoDataFrame, api_key=None, plan='balanced', speed=20, expire=- 1) → geopandas.geoseries.GeoSeries

Compute cycling routes

This function takes origin-destination lines and computes a cycling route between them using the Cycling Streets router.

Parameters

  • api_key (str, defaults to None) – Your registered API key

  • plan (str, defaults to "balanced") –

    The type of route, which can be one of the values: balanced, fastest, quietest. There is also shortest but see the notes below.

    • balanced: We recommend this to be the default route type in your interface - it aims to give practical routes that balance speed and pleasantness, suitable for most riders.

    • fastest: This route type will tend to favour busier roads that suit more confident riders.

    • quietest: The route type will produce more pleasant, but often less direct, routes.

    • shortest: In general we do not recommend including this in your interface unless you have a need for it, as this will not give particularly practical routes. These will be literally the shortest route, with only land ownership rights causing any deviation from this. It will suggest, for instance, dismounting and walking down the opposite direction of a one-way street, and will gladly route over the top of a hill when that is the shortest distance.

  • speed (int, defaults to 20) – The maximum speed at which you will ride. Defaults to 20 km/h. The three permitted speeds are 16, 20, and 24 km/h, which correspond roughly to 10, 12, and 15 miles per hour.

  • expire (int, defaults to -1) – Time after which the cache expires in seconds. Options are: -1 to never expire, 0 to disable caching, or a number. Days can be set using e.g. timedelta(days=180). Defaults to -1.

Returns

GeoSeries with cycling routes

Return type

geopandas.GeoSeries

See also

read_key

Examples

import pandas as pd
import geopandas as gpd
from shapely import wkt
from stplanpy import cycle

# Define two origin-destination lines
df = pd.DataFrame(
    {"geometry": [
    "LINESTRING(-11785727.431 4453819.337, -11782276.436 4448452.023)",
    "LINESTRING(-11785787.392 4450797.573, -11787086.209 4449884.472)"]})

# Convert to WTK
df["geometry"] = gpd.GeoSeries.from_wkt(df["geometry"])

# Create GeoDataFrame
gdf = gpd.GeoDataFrame(df, geometry='geometry', crs="EPSG:6933")

# Read the Cycle Streets API key
cyclestreets_key = cycle.read_key()

# Compute routes
gdf["geometry"] = gdf.routes(api_key=cyclestreets_key)