casageo.spatial module

This module provides spatial routing operations.

General Information

All routing is done independently of time and traffic data by default. To include traffic data in the calculations, set the traffic parameter to True and provide either a departure_time or an arrival_time.

Isolines Queries

Calculate isolines around locations.

Isolines Query Options

departure_infobool: Include additional information about the departure time and location.
arrival_infobool: Include additional information about the arrival time and location.

Isolines Input Columns

The following columns will be read from the input dataframe:

idAny

Fixed identifier to be added to each result of this query.

positionPoint

The center point of the isolines. Instead of a geometry object, you may also specify this as two separate fields position_latitude and position_longitude of type float.

rangeslist[float]

The distances or durations for which to calculate isolines.

ranges_unitstr

The unit for the range values, either "minutes" or "meters". If unset, falls back to reading the field range_type which can either be "time" (minutes) or "distance" (meters).

languagestr

The preferred language for the response. This must be a valid IETF BCP47 language tag, such as "en-US", or a comma-separated list of such tags in order of preference.

unit_systemstr

The system of units to use for localized quantities, either "metric" or "imperial".

transport_modestr

The mode of transport to use for routing, e.g. "car".

routing_modestr

Whether to prefer "fast" or "short" routes.

directionstr

The direction of travel relative to the center point, either "outgoing" or "incoming".

departure_timedatetime

The date and time of departure for time-dependent routing. This value is only used when direction is "outgoing".

arrival_timedatetime

The date and time of arrival for time-dependent routing. This value is only used when direction is "incoming".

trafficbool

Whether to consider traffic data during routing.

When using this feature, you should also specify either departure_time or arrival_time, depending on direction, to get meaningful and reproducible results.

avoid_featuresstr | list[str]

If set, these route features are avoided during routing. This parameter treats a comma-separated string as a list of strings.

exclude_countriesstr | list[str]

If set, these countries are excluded from routing. Must be a sequence of valid ISO 3166-1 alpha-3 country codes. This parameter treats a comma-separated string as a list of strings.

Isolines Output Columns

The resulting dataframe contains the following columns:

idAny: Fixed identifier added to each result of a query.
subidint: Numeric index of the result starting from zero.
geometryMultiPolygon: A MultiPolygon representing the isoline’s geometry.
rangetypestr: String representing the type of the distance value.
rangeunitstr: String representing the unit of the range value.
rangevaluefloat: The distance value represented by this range.
timestampdatetime: Timestamp of when this result was created.

When departure_info is True, the dataframe also contains the columns below. If the direction of the query was not "outgoing", all these values will be null.

departure_timedatetime: Timestamp representing the expected departure time.
departure_placenamestr: Name of the departure location.
departure_positionPoint: Resolved position of the departure location used for route calculation.
departure_displaypositionPoint: Position of a map marker referring to the departure location.
departure_querypositionPoint: The original position provided in the request.

When arrival_info is True, the dataframe also contains the columns below. If the direction of the query was not "incoming", all these values will be null.

arrival_timedatetime: Timestamp representing the expected arrival time.
arrival_placenamestr: Name of the arrival location.
arrival_positionPoint: Resolved position of the arrival location used for route calculation.
arrival_displaypositionPoint: Position of a map marker referring to the arrival location.
arrival_querypositionPoint: The original position provided in the request.

Finally, the dataframe always contains the following error information columns. These contain values only if the corresponding query could not be executed for some reason.

error_codestr: String indicating the type of error.
error_messagestr: Human-readable error message.

Routing Queries

Calculate routes between two locations.

Routing Query Options

departure_infobool: Include additional information about the departure time and location.
arrival_infobool: Include additional information about the arrival time and location.

Routing Input Columns

The following columns will be read from the input dataframe:

idAny

Fixed identifier to be added to each result of this query.

originPoint

The starting point of the route. Instead of a geometry object, you may also specify this as two separate fields origin_latitude and origin_longitude of type float.

destinationPoint

The destination point of the route. Instead of a geometry object, you may also specify this as two separate fields destination_latitude and destination_longitude of type float.

alternativesint

The number of alternate routes to calculate.

languagestr

The preferred language for the response. This must be a valid IETF BCP47 language tag, such as "en-US", or a comma-separated list of such tags in order of preference.

unit_systemstr

The system of units to use for localized quantities, either "metric" or "imperial".

transport_modestr

The mode of transport to use for routing, e.g. "car".

routing_modestr

Whether to prefer "fast" or "short" routes.

departure_timedatetime

The date and time of departure for time-dependent routing.

arrival_timedatetime

The date and time of arrival for time-dependent routing.

trafficbool

Whether to consider traffic data during routing.

When using this feature, you should also specify either departure_time or arrival_time, depending on direction, to get meaningful and reproducible results.

avoid_featuresstr | list[str]

If set, these route features are avoided during routing. This parameter treats a comma-separated string as a list of strings.

exclude_countriesstr | list[str]

If set, these countries are excluded from routing. Must be a sequence of valid ISO 3166-1 alpha-3 country codes. This parameter treats a comma-separated string as a list of strings.

Routing Output Columns

The resulting dataframe contains the following columns:

idAny: Fixed identifier added to each result of a query.
subidint: Numeric index of the result starting from zero.
geometryMultiLineString: Geometry of the route by sections.
lengthfloat: Total length of the route in meters.
durationfloat: Total duration of the route in minutes.
timestampdatetime: Timestamp of when this result was created.

When departure_info is True, the dataframe also contains the columns below. If the direction of the query was not "outgoing", all these values will be null.

departure_timedatetime: Timestamp representing the expected departure time.
departure_placenamestr: Name of the departure location.
departure_positionPoint: Resolved position of the departure location used for route calculation.
departure_displaypositionPoint: Position of a map marker referring to the departure location.
departure_querypositionPoint: The original position provided in the request.

When arrival_info is True, the dataframe also contains the columns below. If the direction of the query was not "incoming", all these values will be null.

arrival_timedatetime: Timestamp representing the expected arrival time.
arrival_placenamestr: Name of the arrival location.
arrival_positionPoint: Resolved position of the arrival location used for route calculation.
arrival_displaypositionPoint: Position of a map marker referring to the arrival location.
arrival_querypositionPoint: The original position provided in the request.

Finally, the dataframe always contains the following error information columns. These contain values only if the corresponding query could not be executed for some reason.

error_codestr: String indicating the type of error.
error_messagestr: Human-readable error message.

casageo.spatial.DEFAULT_LANGUAGE: str = 'en-US': The default language used in the results.

casageo.spatial.DEFAULT_UNIT_SYSTEM: str = 'metric': The default unit system used in the results.

casageo.spatial.DEFAULT_TRANSPORT_MODE: str = 'car': The default transport mode.

casageo.spatial.DEFAULT_ROUTING_MODE: str = 'fast': The default routing mode.

casageo.spatial.DEFAULT_DIRECTION: str = 'outgoing': The default routing direction.

casageo.spatial.DEFAULT_DEPARTURE_TIME: datetime | None = None: The default departure time.

casageo.spatial.DEFAULT_ARRIVAL_TIME: datetime | None = None: The default arrival time.

casageo.spatial.DEFAULT_TRAFFIC: bool = False: The default setting of the traffic option.

casageo.spatial.DEFAULT_AVOID_FEATURES: tuple[str, ...] = (): The default list of route features to avoid.

casageo.spatial.DEFAULT_EXCLUDE_COUNTRIES: tuple[str, ...] = (): The default list of countries to exclude from the search.

casageo.spatial.DEFAULT_RANGE_UNIT: str = 'minutes': The default unit for range values.

casageo.spatial.DEFAULT_ALTERNATIVES: int = 0: The default number of alternative routes to compute.

casageo.spatial.isolines(client, queries, defaults=None, *, departure_info=False, arrival_info=False)

Calculate isolines around locations.

See Isolines Queries in the module documentation.

Parameters:

client (CasaGeoClient) – The client object authorizing these queries.
queries (DataFrame) – The dataframe of queries.
defaults (dict | None) – An optional dict of default values for missing input columns.
departure_info (bool) – Include additional information about the departure time and location.
arrival_info (bool) – Include additional information about the arrival time and location.

Returns:

The list of results as an EPSG:4326 GeoDataFrame. The shape is described under Isolines Output Columns in the module documentation.

The geometry column of the dataframe is the geometry column.

Return type:

GeoDataFrame

Raises:

InsufficientCreditsError – If the account does not have enough credits.
CasaGeoError – If the request could not be executed for another reason.

casageo.spatial.routes(client, queries, defaults=None, *, departure_info=False, arrival_info=False)