Quick Start Overview

12How to create a route with PTV Developer

Documentation Links

Refer to the official PTV Developer documentation for detailed information:

• Routing API Reference
• Vehicle Profiles documentation
• Waypoints documentation
• Geocoding & Places API Reference

Results Parameters

The following results parameters are required when requesting a route calculation. They define what data the API response includes:

• ROUTE_ID Unique identifier for the calculated route
• LEGS Individual leg details between consecutive waypoints
• LEGS_POLYLINE Polyline geometry for each leg
• TOLL_COSTS Toll cost information along the route
• POLYLINE Complete route polyline geometry
• WAYPOINT_EVENTS Events at each waypoint (arrival, departure)

Vehicle Profile

Predefined vehicle profile names from the PTV Data API are used for routing. The profile determines routing constraints such as vehicle dimensions, weight limits, and road restrictions. For example:

EUR_TRAILER_TRUCK — A standard European trailer truck profile commonly used for long-haul transport routing.

Waypoint Types

OnRoadWaypoint — A waypoint that snaps to the nearest road segment.

• type OnRoadWaypoint
• latitude Latitude coordinate in decimal degrees
• longitude Longitude coordinate in decimal degrees

OffRoadWaypoint — A waypoint used to manipulate the route so it goes a different way. Unlike OnRoadWaypoints, OffRoadWaypoints do not snap to a road. By placing an OffRoadWaypoint with a radius, you force the route through a specific area, effectively changing the path the route takes. This is useful when you want to influence the routing to use a particular road or passage.

• type OffRoadWaypoint
• latitude Latitude coordinate in decimal degrees
• longitude Longitude coordinate in decimal degrees
• radius Search radius in meters — defines the area around the waypoint where the route must pass through

Example Request URL

The following example shows a complete GET request combining the API endpoint, waypoints (including an OffRoadWaypoint to manipulate the route), vehicle profile, and results parameters:

Note: The second waypoint uses ;radius=20 making it an OffRoadWaypoint that manipulates the route to pass through that area.

Route Calculation — Required Parameters for PTV Navigator G2

Routes are pushed to PTV Navigator G2 with the full route geometry (GuidedNavigation) so the device follows the exact path your back-end calculated.

GuidedNavigation (Stops + Geometry)

The route response must include all of the following:

• Results Parameters POLYLINE,TOLL_COSTS,ROUTE_ID,LEGS,LEGS_POLYLINE,WAYPOINT_EVENTS
• API Endpoint https://api.myptv.com/routing/v1/routes
• API Key Header The API key is passed via the apiKey HTTP header
• HTTP Method GET
• Currency Option When TOLL_COSTS is included in the Results Parameters, the application additionally sends options[currency]=EUR
• Waypoint Format Waypoints are passed as repeated waypoints query parameters. OnRoadWaypoint: latitude,longitude — OffRoadWaypoint: latitude,longitude;radius=20
• Vehicle Profile The vehicle profile is passed as the profile query parameter when using a predefined profile name

3How to push a route to PTV Navigator G2

Overview

The PTV Navigator Push Service lets your system send a calculated route directly to a PTV Navigator G2 device. The driver sees a notification and can accept or decline it. Your system polls a status endpoint to find out what happened. There is no callback or webhook — your system is responsible for polling until a final result is available.

Device Prerequisite — Enable the Push Service

Before a device can receive pushed routes, the Push Service must be enabled on that device. This feature is available with PTV Navigator G2 app version 1.7.0 and newer, and it is turned off by default.

You activate it through the device's preferences file, which is managed via remote configuration in the licensing portal:

1. Generate the preferences file using the Preferences Generator. The Push Service option (“Receive Routes”) is shown in the preview section of the generator — enable it there before generating the file. See the Preferences Generator documentation.
2. Upload the generated preferences file to the remote configuration in the licensing portal, so it is distributed to the device(s). See the Remote Configuration documentation.

Once the preferences file is applied, the device will accept pushed routes. If the Push Service is not enabled on the device, push requests will not reach the driver.

Concept in Three Steps

1. Push — Your backend uploads a route file for a specific device. The service returns a requestId.
2. Notify — The service pushes a notification to PTV Navigator G2 via Firebase Cloud Messaging. The driver accepts, declines, or the request times out.
3. Poll — Your backend calls the result endpoint periodically with the requestId until it gets a final status (accepted, declined, error, or timeout). You are waiting for a drivers response. Polling frequency should be >30 seconds.

File Format Recommendation

For guided, turn-by-turn navigation (action=navigateRoute or calcRoute), JSON is strongly recommended — it's the native output of the PTV Developer Routing API and gives PTV Navigator G2 the best route quality. BCR is a legacy format and should be treated as a fallback.

Route Mode

Routes are pushed as Guided Navigation: the full route JSON including polyline and legs[].polyline is sent. The device follows the pre-calculated path with turn-by-turn instructions. This requires POLYLINE and LEGS_POLYLINE in the results parameters.

The API — Two Endpoints

• POST /{licenseKey}/push-data-to-device Send a route to a device
• GET /{licenseKey}/get-result/{requestId} Check delivery/response status

Base URL: https://api.myptv.com/navigator/v1/push
All calls require ?apiKey=YOUR_LICENSE_KEY

Required Parameters (Push Step)

Sent as multipart/form-data:

• installationId UUID v4 identifying the target device (required)
• dataType routeJson or routeBcr (required)
• action calcRoute or navigateRoute (required)
• fileName Original file name, must match the extension for chosen dataType (required)
• data The route file itself, binary upload, max 10 MB (required)
• title Custom notification title shown to the driver (optional, max 80 characters)
• message Custom notification message shown to the driver (optional, max 500 characters)
• positiveBtnTxt Custom text for the accept button (optional, max 30 characters)
• negativeBtnTxt Custom text for the decline button (optional, max 30 characters)

Result Polling

Poll get-result/{requestId} every 30 seconds. A response with errorTypeId: null means "not yet answered — keep polling." Any other value is final:

• 0 Accepted — driver accepted the route
• 1 Declined — driver declined the route
• 2 Error — device-side error
• 3 Timeout — driver didn't respond

Pushed data is discarded automatically after 7 days regardless of outcome.

License Key & Installation ID

A license key groups one or more device installations. Each installation ID uniquely identifies a single PTV Navigator G2 device within a license key. When sending a route, you first select the license key to narrow down the available devices, then choose the specific installation ID of the target device.

JSON Route Format

The JSON route format is the complete Routing API response obtained with all required Results Parameters. This response is sent to PTV Navigator G2 devices without any transformation — the full JSON payload as returned by the API is the file transferred to the device.

Example Push Request

The following example shows a complete POST request to send a route JSON file to a device. Replace YOUR_LICENSE_KEY with your license key and INSTALLATION_ID with the target device UUID:

Response: { "requestId": "91b73204-6902-4450-adcc-519bc7742183" } — save this ID for polling.

Example Poll Request

After pushing, poll the result endpoint every 10 seconds until errorTypeId is no longer null:

Pending response: { "requestId": "...", "errorTypeId": null, "params": null, "date": null }
Final response (accepted): { "requestId": "...", "errorTypeId": 0, "params": null, "date": "2026-07-20T14:35:22Z" }