API¶

ApiClient¶

Official Python SDK for Route4Me

Consists of classes:

access to all Route4Me API’s endpoints;
convenient models for Route4Me’s entities;
constants and enums;

Look out the appropriate section for details.

class route4me.sdk.ApiClient(api_key=None)[source]¶

Bases: object

Route4Me API client

Provides an access to API’s endpoints through a convenient interface. In other words, all the power of Route4Me API is accessible through this class.

__init__(api_key=None)[source]¶

geocodings¶

Geocodings endpoint functions

Returns:	Geocoding namespace
Return type:	`Geocodings`

optimizations¶

Optimization endpoint functions

Returns:	Optimization namespace
Return type:	`Optimizations`

Endpoints¶

Geocoding¶

Geocoding is the process of converting addresses (like “1600 Amphitheatre Parkway, Mountain View, CA”) into geographic coordinates (like “latitude 37.423021 and longitude -122.083739”), which you can use to place markers on a map or position the map.

See also

https://route4me.io/docs/#geocoding

class route4me.sdk.endpoints.geocodings.Geocodings(api_key=None, _network_client=None)[source]¶

Bases: object

Geocondings stuff

__init__(api_key=None, _network_client=None)[source]¶

Optimizations¶

An Optimization Problem refers to a collection of addresses that need to be visited.

The optimization problem takes into consideration all of the addresses that need to be visited and all the constraints associated with each address and depot.

It is preferable to create an optimization problem with as many orders in it as possible, so that the optimization engine is able to consider the entire problem set.

This is different from a Route, which is a sequence of addresses that need to be visited by a single vehicle and driver in a fixed time period. Solving an Optimization Problem results in a number of routes. (Possibly recurring in the future)

See also

https://route4me.io/docs/#optimizations

class route4me.sdk.endpoints.optimizations.Optimizations(api_key=None, _network_client=None)[source]¶

Bases: object

Optimizations endpoint

__init__(api_key=None, _network_client=None)[source]¶

create(optimization_data, optimized_callback_url=None)[source]¶

Create a new optimization through the Route4Me API

You could pass any valid URL as :paramref:`optimized_callback_url` parameter.

The callback URL is a URL that gets called when the optimization is solved, or if there is an error. The callback is called with a POST request. The example of the POST data sent:

{
        "timestamp": 1500111222,        // seconds
        "state": 4,                     // ID of the optimization state

        // ID of Optimization Problem
        "optimization_problem_id": "1EDB78F63556D99336E06A13A34CF139"
}

The state is a value from the enumeration OptimizationStateEnum

Parameters:	optimization_data (Optimization or dict) – Optimization data optimized_callback_url (str or None, optional) – Optimization done callback URL, defaults to None
Returns:	New optimization
Return type:	Optimization

get(ID)[source]¶

GET a single optimization by ID.

Parameters:	ID (str) – Optimization Problem ID
Returns:	Optimization data
Return type:	Optimization
Raises:	Route4MeEntityNotFoundError – if optimization was not found

list(states=None, limit=None, offset=None)[source]¶

GET all optimizations belonging to a user.

Optionally filtered

Parameters:	states (str or list(str) or list(OptimizationStateEnum), optional) – Comma separated list of states, you can pass one CSV string or any enumerable of state IDS (string and enums are supported), defaults to None limit (int, optional) – Search limitation, defaults to None offset (int, optional) – Search starting position, defaults to None

remove(ID)[source]¶

Remove an existing optimization belonging to an user.

Parameters:	ID (str) – Optimization Problem ID
Returns:	Always `True`
Return type:	bool
Raises:	Route4MeApiError – if Route4Me API returned not expected response Route4MeEntityNotFoundError – if optimization was not found

reoptimize(ID)[source]¶: An alias for update(), with reoptimize set to True

update(ID, optimization_data=None, reoptimize=False)[source]¶

Update existing optimization problem, by changing some parameters or addresses. Optionally you can re-run the optimization engine for the optimization problem

Notice, that you can re-run optimization without modifications.

Parameters:	ID (str) – Optimization problem ID optimization_data (Optimization or dict, optional) – Optimization data, defaults to None reoptimize (bool, optional) – Whether to re-run optimization, defaults to `False`
Returns:	Updated optimization
Return type:	Optimization

Data Structures¶

Models¶

class route4me.sdk.models.Address(raw=None)[source]¶

Bases: route4me.sdk.models.BaseModel

Single Address, also known as Route Destination

See also

api doc: https://route4me.io/docs/#addresses
schema: https://github.com/route4me/route4me-json-schemas/blob/master/Address.dtd

ID¶

Route Destination ID

Internal unique address identifier

Getter:	Gets value
Setter:	Sets value
Return type:	str

__init__(raw=None)[source]¶

Create instance LOCALLY.

Use add_address() or add_address() to create new Address in the Route4Me API

Parameters:	raw (dict, optional) – Raw values for new address, example: add address to optimization, defaults to `None`

address¶

The route’s Address Line

Note

In Route4Me API this field is known as address

Getter:	Get
Setter:	Set
Return type:	str

address_stop_type¶

Address stop type

Getter:	Get
Setter:	Set
Return type:	AddressStopTypeEnum

failed_geocoding¶

True means there was a geocoding attempt which failed. False means success or no geocoding

Getter:	Get
Setter:	Set
Return type:	bool

geocoded¶

True means the address_string field was successfully geocoded

Getter:	Get
Setter:	Set
Return type:	bool

is_depot¶

Indicates that this address is a depot

Getter:	Get
Setter:	Set
Return type:	bool

latitude¶

Latitude

Shoud be -90.0 ≤ lat ≤ 90

Note

In Route4Me API this field is known as lat

Getter:	Get
Setter:	Set
Return type:	float

longitude¶

Longitude

Shoud be -180.0 ≤ lng ≤ 180

Note

In Route4Me API this field is known as lng

Getter:	Get
Setter:	Set
Return type:	float

name¶

Address Alias / Address Name

Note

In Route4Me API this field is known as alias

Getter:	Get
Setter:	Set
Return type:	str

route_id¶

Route ID

Parent route

Getter:	Get
Setter:	Set
Return type:	str

sequence_no¶

The sequence number for the address

Getter:	Get
Setter:	Set
Return type:	int

service_time_sec¶

Service time (seconds)

Note

In Route4Me API this field is known as time

Getter:	Get
Setter:	Set
Return type:	int

class route4me.sdk.models.Optimization(raw=None)[source]¶

Bases: route4me.sdk.models.BaseModel

Optimization problem (or simple Optimization)

See also

schema: https://github.com/route4me/route4me-json-schemas/blob/master/Optimization_response.dtd

__init__(raw=None)[source]¶

Create instance LOCALLY.

Use create() to create new Optimization Problem in the Route4Me API

Parameters:	raw (dict, optional) – Raw values for new optimization, example: create optimization, defaults to None

addresses¶

Addresses included to this Optimization Problem

<AUTO>

algorithm_type¶

The algorithm type to be used

Getter:	Get
Setter:	Set
Return type:	AlgorithmTypeEnum

device_id¶

Device ID

32 Character MD5 String ID of the device that was used to plan this route

Getter:	Get
Setter:	Set
Return type:	str

device_type¶

Device type

The type of the device that is creating this Optimization Problem

Getter:	Get
Setter:	Set
Return type:	DeviceTypeEnum

disable_optimization¶

By disabling optimization, the route optimization engine will not resequence stops in your optimization problem

Getter:	Get
Setter:	Set
Return type:	bool

links¶

Links to the GET operations for the optimization problem

Getter:	Get
Setter:	Set
Deleter:	Del
Return type:	dict or None

member_id¶

Member ID

User ID who is assigned to this Optimization Problem

Getter:	Get
Setter:	Set
Return type:	int

metric¶

Metric

Getter:	Get
Setter:	Set
Return type:	RouteMetricEnum

name¶

The name of this optimization problem. This name will be accessible in the search API, and also will be displayed on the mobile device of a user

Getter:	Get
Setter:	Set
Return type:	str

optimization_factor¶

The driving directions can be generated biased for this selection. This has no impact on route sequencing.

Note

In Route4Me API this enum also known as optimize

Getter:	Get
Setter:	Set
Return type:	OptimizationFactorEnum

parts¶

Legacy feature which permits a user to request an example number of optimized routes

Getter:	Get
Setter:	Set
Return type:	int

quality¶

Optimization quality

There are 3 types of optimization qualities that are optimizations goals, see OptimizationQualityEnum

Getter:	Get
Setter:	Set
Return type:	OptimizationQualityEnum

round_trip¶

Round Trip

The tour type of this route. The optimization engine changes its behavior for round trip routes

Note

In Route4Me API this parameter is also known as parameters.rt

Getter:	Get
Setter:	Set
Return type:	bool

route_datetime¶

Route DateTime

Note

In Route4Me API this parameter is broken into 2 parts: fields parameters.route_date and parameters.route_time

Getter:	returns a `datetime` combining values from two fields
Setter:	sets `parameters.route_date` and `parameters.route_time` in the raw data
Return type:	datetime

route_max_duration_sec¶

Route maximum duration

How many seconds a route can last at most. Default is 86400 seconds = 24 hours

Getter:	Get
Setter:	Set
Return type:	int

state¶

The current state of the optimization

Getter:	Get
Setter:	Set
Return type:	OptimizationStateEnum

travel_mode¶

Travel mode

The mode of travel that the directions should be optimized for

Getter:	Get
Setter:	Set
Return type:	TravelModeEnum

vehicle_id¶

Vehicle ID

The unique internal id of a vehicle

Getter:	Get
Setter:	Set
Return type:	str

Enums and constants¶

class route4me.sdk.enums.AddressStopTypeEnum[source]¶

Bases: route4me.sdk.enums.PEnum

Address stop type

BREAK = 'BREAK'¶: Break

DELIVERY = 'DELIVERY'¶: Delivery

MEETUP = 'MEETUP'¶: Meetup

PICKUP = 'PICKUP'¶: Pickup

class route4me.sdk.enums.AlgorithmTypeEnum[source]¶

Bases: route4me.sdk.enums.PEnum

The algorithm type to be used.

ALG_LEGACY_DISTRIBUTED = 101¶: ALG_LEGACY_DISTRIBUTED

ALG_NONE = 100¶: ALG_NONE

BBCVRP = 7¶: BBCVRP

CVRP_TW_MD = 4¶: CVRP_TW_MD

CVRP_TW_SD = 3¶: CVRP_TW_SD

TSP = 1¶: TSP

TSP_TW = 5¶: TSP_TW

TSP_TW_CR = 6¶: TSP_TW_CR

VRP = 2¶: VRP

class route4me.sdk.enums.DeviceTypeEnum[source]¶

Bases: route4me.sdk.enums.PEnum

Device Type

The type of the device that is creating this route

ANDROID_PHONE = 'android_phone'¶: Android phone

ANDROID_TABLET = 'android_tablet'¶: Android tablet

IPAD = 'ipad'¶: IPad

IPHONE = 'iphone'¶: IPhone

WEB = 'web'¶: Web

class route4me.sdk.enums.DistanceUnitEnum[source]¶

Bases: route4me.sdk.enums.PEnum

Optimization problem can be at one state at any given time

KILOMETER = 'km'¶: Kilometers

MILE = 'mi'¶: Miles

class route4me.sdk.enums.OptimizationFactorEnum[source]¶

Bases: route4me.sdk.enums.PEnum

The driving directions can be generated biased for this selection. This has no impact on route sequencing.

Note

In Route4Me API this enum also known as optimize

DISTANCE = 'Distance'¶: Optimize by distance

TIME = 'Time'¶: Optimize by time

TIME_TRAFFIC = 'timeWithTraffic'¶: Optimize by time and traffic

class route4me.sdk.enums.OptimizationQualityEnum[source]¶

Bases: route4me.sdk.enums.PEnum

Optimization Quality

BEST = 3¶: Generate The Shortest And Quickest Possible Routes

FAST = 1¶: Generate Optimized Routes As Quickly as Possible

MEDIUM = 2¶: Generate Routes That Look Better On A Map

class route4me.sdk.enums.OptimizationStateEnum[source]¶

Bases: route4me.sdk.enums.PEnum

The distance measurement unit

COMPUTING_DIRECTIONS = 6¶: Computing Directions

ERROR = 5¶: Error

INITIAL = 1¶: Initial

MATRIX_PROCESSING = 2¶: Matrix Processing

OPTIMIZED = 4¶: Optimized

OPTIMIZING = 3¶: Optimizing

class route4me.sdk.enums.PEnum[source]¶

Bases: enum.Enum

An enumeration.

classmethod parse_many(value)[source]¶

Parses enum items from string/list

Parameters:	value (str or list or OptimizationStateEnum) – string or enumerable with enum items
Returns:	list of parsed items
Return type:	str or list(str) or list(OptimizationStateEnum)

class route4me.sdk.enums.RouteMetricEnum[source]¶

Bases: route4me.sdk.enums.PEnum

Metric

EUCLIDEAN = 1¶: Euclidean

EXACT2D = 5¶: Exact 2d

GEODESIC = 3¶: Geodesic

MANHATTAN = 2¶: Manhattan

MATRIX = 4¶: Matrix

class route4me.sdk.enums.TravelModeEnum[source]¶

Bases: route4me.sdk.enums.PEnum

Travel Mode

The mode of travel that the directions should be optimized for

CYCLING = 'Cycling'¶: Cycling

DRIVING = 'Driving'¶: Driving

TRANSIT = 'Transit'¶: Transit

TRUCKING = 'Trucking'¶: Trucking

WALKING = 'Walking'¶: Walking