Migration Guide

This guide is intended for developers migrating from Chargetrip’s legacy Route service to the latest version of the Route service. If you have any additional questions, please contact our support team.

The new Route service delivers key improvements, including a streamlined and reorganized schema, per-country operator preferences, faster route computation, and greater maintainability. The legacy service will remain available until May 2026, after which all legacy operations will be removed from the schema.

Introduction

The new Route service consolidates the legacy five operations to four. While the operation names and schema have changed, the usage pattern for creating and retrieving routes continues to rely on the same type of GraphQL operations—query, mutation, and subscription.

The table below maps the legacy Route service operations to their corresponding operations in the new Route service:

General schema changes

Below you can find an overview of general schema changes that apply to all operations.

Mutation changes

This section details all changes to the input schema between the legacy newRoute mutation and the new createRoute mutation. For complete schema definitions and usage, see mutate to create a new route.

Schema reorganization

The input field has been restructured in the new Route service. The legacy fields - routeRequest, ev, and telemetry — have been flattened and reorganized.

routeRequest

The routeRequest fields have been moved directly under the input and input.vehicle.charging.

EV

The ev fields are now structured under the vehicle object or redistributed across origin, via, and other typed properties.

Telemetry

The telemetry fields are now structured under the vehicle object and moved into a strongly typed reference.

Extended operator preferences

Operator ranking levels have been simplified to low, medium, and high. Additionally, preferences can be scoped per country using the countries field. Note: To apply preferences globally (as in the legacy service), either omit the countries field or set it as an empty array.

          operators: {    ranking: {        type: preferred,        levels: {            # Operator only uses a high preference in the Netherlands.            high: [                {                     id: "op1",                     countries: [NL]                }            ],             # Operator uses a low preference globally.            low: [                {                    id:"op3"                }            ]         }    }    # Operator is excluded globally.    exclude: [        {             id: "op2"        }    ]}
        

Total occupant weight

Cargo and occupant information have been moved to properties.vehicle under origin and via location points. Moreover, the default occupants' weight can now be overridden by setting the total_occupant_weight. This field can only be used in combination with occupants.

          origin {    vehicle {        occupants: 3        total_occupant_weight: {            value: 160            type: kilogram            source: manual        }    }}
        

Query / subscription changes

This section details all changes to the legacy route and routePath queries and the routeUpdateById subscription in comparison to the getRoute query and route subscription. For complete schema definitions and usage, see Subscribe to route updates and Query route details.

Schema reorganization

The new Route service response, for both the getRoute query and route subscription, has the following changes:

• Consolidated top-level fields from 7 to 5.
• Unified Input Representation under request_input.

Top level response

The table below maps the legacy route request / subscription fields to their corresponding query / subscription fields in the new Route service:

Route

The legacy route field has been renamed to recommended and reorganized to improve clarity and extensibility.

Legs

The legs field has been updated with several improvements. The origin.properties and destination.properties fields are now typed, replacing the previous free-form JSON format. Range data has been reorganized under range_at_origin and range_at_destination, and a new range_after_charge field has been added. Lastly, the steps field has been renamed to sections. See the “Steps” section below for more details.

Steps

steps are now replaced with sections. Sections provide additional information — such as origin and destination — and make it easy to identify different road characteristics to display on a frontend.

          sections {  type  tags  polyline(decimals: five)  distance(unit: meter)  duration  consumption  origin {    id    type    properties {      occupants      total_occupant_weight      total_cargo_weight    }    geometry {      type      coordinates    }  }  destination {    id    type    properties {      occupants      total_occupant_weight      total_cargo_weight    }    geometry {      coordinates      type    }  }}