Search for content

Frequently Asked Questions

Account

How can I start using the PTV Developer APIs?

You need to sign up for a PTV account and then activate your free subscription of PTV Developer. If you already have a PTV account, you can directly activate your free product. No payment details are needed to activate your free product.

Can I activate more than one free subscription?

No. Every account can only activate one free subscription of PTV Developer but multiple paid subscriptions.

Where can I update my personal data?

You can use the avatar menu on the top right corner to reach the Manage Profile section and update your personal information.

Where can I delete my account?

In the Manage Profile section you have the possibility to delete your account. Please note that you can only delete your account if no subscription is active.

Developer Support

How can I generate API keys to start developing?

Within your product instance you can create, rename and delete API keys in the API Keys App.

How many API keys can I create using a free subscription?

For the free subscription one API key is included. If you need more API keys, please contact us and we will find a solution that fits best to your needs.

How do I use the API keys?

The API keys are needed to authenticate against PTV Developer APIs. Check the Quick Start of the API documentations for more details on the authentication options.

How can I run performance tests on PTV Developer APIs?

If you want to run performance or load tests, please contact us and we will find a solution that fits best to your needs.

How can I generate client classes for PTV Developer APIs?

Learn how to generate clients for PTV Developer APIs in this tutorial. Alternatively you can download clients for Java, C# and TypeScript from GitHub.

What does the version number of PTV Developer APIs mean?

The version number consists of three fields, namely major.minor.bugfix, e.g. 1.2.3. The exact version number can be found in the API Changes of each PTV Developer API, the first two fields can also be found in the API specification.

All PTV Developer APIs will be backward compatible as long as the major version does not change (e.g. 1.x.x). 

Changing the minor version (e.g. 1.2.x) denotes compatible API extensions so that there will be a benefit from updating the clients. 

Changing the bugfix version (e.g. 1.2.3) denotes fixes which do not affect the API such as functional bugfixes, documentation etc.

How do PTV Developer APIs handle compatiblity?

Clients should follow some rules which are common practice in the communication with APIs to guarantee compatibility. We handle the following changes as being compatible:

  • New operations.
  • New optional properties in requests. There will never be new required properties in requests.
  • New optional and required properties in responses, the client should be robust against these changes and be tolerant with unknown fields. Response properties marked as required give the client a hint that this property will always be present so that checks for existence can be omitted.
  • New values in enumerations used only in requests.
  • New values in enumerations used in responses if being sent only when explicitly requested by a new property introduced in the same version.
  • New values in string properties flagged as 'x-extensible-enum', the client should implement a fallback mechanism for unknown values.
  • Relaxing constraints of properties such as increasing array lengths, extending value ranges or removing string patterns.

Compatibility is guaranteed only for the messages sent and received (sometimes referred to as 'on the wire'). Any code generated from the API specification is not covered. The semantics of the properties will be stable, but the contents of properties may change as algorithms evolve, results will improve and data will be updated regularly.

Properties may be marked as deprecated. That means that they will still be supported but their use is discouraged. See the documentation for information on which property to use instead.

What does the experimental tag for PTV Developer APIs mean?

The term "experimental" denotes a service or feature that is still in the early phases of development. It could still be going through extensive testing and not be completely stable.

  • API stability: An experimental feature or service's API may be unstable. This implies that depending on the input or the direction of the work, it could alter regularly or, in certain cases, it might be entirely removed.
  • Completeness: A feature or service that is still being tested may not be fully functioning. It offers a sneak preview of something that is still in the development stage.
  • Documentation: It is labelled with the tagline [EXPERIMENTAL].

What does the preview tag for PTV Developer APIs mean?

The term "preview" refers to a service or feature that is more developed than an experimental one. Although the core functions are established and reliable, it could still be missing some features that are planned for the full release.

  • API Stability: A preview feature or service's API is stable, indicating users may anticipate predictable behavior and replies.
  • Completeness: A feature or service is more comprehensive than an experimental one. The majority of the functions are available, however certain intended features could be absent at this time; these features will be introduced in the future.
  • Documentation: It is labelled with the tagline [PREVIEW].

How can I avoid 404 (Not Found) error codes even though my url seems to be ok?

If the endpoint requires a parameter in the path and this parameter is missing you will get a http response code 404 (Not Found) even if the rest of the url is correct. You have to add the required parameter to the url in order to get a successful response or an error message with more details if something else is wrong with the parameter.

Licensing & Terms

Can I use a free subscription for productive/commercial use of my application?

The free subscription is only for testing and integration purposes. If you want to roll out your application for commercial use, you need to contact us and we will find a solution that fits best to your needs.

What are the terms of use?

You can find the terms of use for different regions by using the according link below.

EU - English
EU - German
US - English

What are the limits for the free and standard subscriptions?

The Free Plan is intended for testing of the API services and can be used free of charge with a simplified registration. The Standard Plan offers productive use for simple applications. This plan can easily be extended with a pay-as-you-go model. All limits of our freely bookable plans are listed below. For more complex use cases, we provide our customers with individual pricing plans that have no separate limits. Please get in touch with us for further information.

APIMethodFree PlanStandard Plan
Geocoding & Places API-No additional limitNo additional limit
Geocoding & Places OSM API-No additional limitNo additional limit
Raster Maps API-No additional limitNo additional limit
Vector Maps API-No additional limitNo additional limit
Vector Maps OSM API-No additional limitNo additional limit
Map Matching API-No additional limitNo additional limit
Routing API-No additional limitNo additional limit
Routing OSM API-No additional limitNo additional limit
Matrix Routing APIcalculateMatrix (sync)250 matrix relations per requestNo additional limit
startMatrixCalculation (async)250 matrix relations per requestNo additional limit
Matrix Routing OSM APIcalculateMatrix (sync)250 matrix relations per requestNo additional limit
startMatrixCalculation (async)250 matrix relations per request No additional limit
EWS Road Distance APIgetRelation100 requests per month100 requests per month
Route Optimization APIcreatePlan25 transports per requestNo additional limit
Route Optimization OptiFlow APIstartOptimization20 locations per request
20 orders per request
5 vehicles per request
5 minutes runtime per request
25 locations per request
25 orders per request
5 vehicles per request
5 minutes runtime per request
Sequence Optimization APIstartAndCreateOptimizedRoute25 transports per requestNo additional limit
Loading Space Optimization APIstartBinPacking (async)5 bins per request
100 items per request
No additional limit
Data API-No additional limitNo additional limit

What are request limits?

Request limits define a maximum amount of objects in a single call of the services (e.g. number of waypoints per routing request). If the limits are reached it is recommended to split up the amount of objects into multiple requests. For some APIs there are no request limits because the endpoints handle only single objects (e.g. map tiles, addresses or coordinates). Depending on your current subscription lower or higher limits may apply.

Find the request limits per service in the table below.

APIMethodRequest limits
Geocoding & Places API-No request limits
Geocoding & Places OSM API-No request limits
Raster Maps API-No request limits
Vector Maps API-No request limits
Vector Maps OSM API-No request limits
Map Matching APIcreateMatchedTrack16,200 positions per request
Routing APIcalculateRoute25 waypoints per request
calculateRoutePost250 waypoints per request
Routing OSM APIcalculateRoute25 waypoints per request
Matrix Routing APIcalculateMatrix (sync)250,000 matrix relations per request
startMatrixCalculation (async)4,000,000 matrix relations per request
Matrix Routing OSM APIcalculateMatrix (sync)250,000 matrix relations per request
startMatrixCalculation (async)4,000,000 matrix relations per request 
(250,000 matrix relations for time-dependent matrices)
EWS Road Distance API-No request limits
Route Optimization APIcreatePlan3,000 transports per request
Route Optimization OptiFlow APIstartOptimization

4,000 locations per request
10,000 orders per request
1,000 vehicles per request
24 hours runtime per request

Depending on your current subscription lower or higher limits may apply.

Sequence Optimization APIstartAndCreateOptimizedRoute500 transports per request
Loading Space Optimization APIpackBins (sync)2 bins per request
100 items per request
startBinPacking (async)100 bins per request
10,000 items per request
Data API-No request limits

What are rate limits?

Rate limits are the number of requests per given time period a single API key can make. If those limits are exceeded, the error code 'GENERAL_RATE_LIMIT_EXCEEDED' is returned and further requests will temporarily be rejected (sliding window based). Please note that the rejection in one API does not affect other APIs.

Find the rate limits per service in the table below.

APIMethodRate limits
Geocoding & Places APIsearchLocationsByText2,000 requests per minute
getSuggestionsByText2,000 requests per minute
searchLocationsByAddress2,000 requests per minute
getSuggestionsByAddress2,000 requests per minute
searchLocationsByPosition10,000 requests per minute
All other methods600 requests per minute
Geocoding & Places OSM APIAll methods600 requests per minute
Raster Maps APIgetSatelliteTile2,500 requests per minute
All other methods10,000 requests per minute
Vector Maps APIAll methods10,000 requests per minute
Vector Maps OSM APIAll methods10,000 requests per minute
Map Matching APImatchPosition10,000 requests per minute
All other methods300 requests per minute
Routing APIstartAndCreateReachableAreas (async)50 requests per minute
startAndCreateReachableLocations (async)50 requests per minute
All other methods500 requests per minute
Routing OSM APIstartAndCreateReachableAreas (async)50 requests per minute
All other methods500 requests per minute
Matrix Routing APIcalculateMatrix (sync)500 requests per minute
startMatrixCalculation (async)50 requests per minute
getStatus3,000 requests per minute
All other methods100 requests per minute
Matrix Routing OSM APIcalculateMatrix (sync)500 requests per minute
startMatrixCalculation (async)50 requests per minute
getStatus3,000 requests per minute
All other methods100 requests per minute
EWS Road Distance APIAll methods600 requests per minute
Route Optimization APIstartOptimization50 requests per minute
getOperationStatus3,000 requests per minute
All other methods100 requests per minute
Route Optimization OptiFlow APIstartOptimization

10 requests per minute

1 optimization at a time

All other methods50 requests per minute
Sequence Optimization APIstartAndCreateOptimizedRoute50 requests per minute
getOptimizedRoute3,000 requests per minute
All other methods100 requests per minute
Loading Space Optimization APIpackBins (sync)20 requests per minute
startBinPacking (async)50 requests per minute
getStatus3,000 requests per minute
All methods100 requests per minute
Data APIAll methods300 requests per minute

How are transactions calculated?

To measure the transactions 1k packages are used as measurement unit. Your usage of all offered services is simply added up.

APIMethod1k transactions correspond to...
Geocoding & Places APIsearchLocationsByText1,000 texts
getSuggestionsByText100,000 suggestions
searchLocationsByAddress1,000 addresses
getSuggestionsByAdress100,000 suggestions
searchLocationsByPosition1,000 positions
searchPlacesByText1,000 texts
searchPlacesByPosition1,000 positions
searchPlacesByArea1,000 areas
Geocoding & Places OSM APIsearchPlacesByText1,000 texts
searchPlacesByAddress1,000 addresses
searchPlacesByPosition1,000 positions
Raster Maps APIgetImageTile15,000 image tiles
getDataTile15,000 data tiles
getSatelliteTile5,000 satellite tiles
Vector Maps APIgetVectorTile15,000 vector tiles
 getTile (overlays)15,000 vector tiles
Vector Maps OSM APIgetVectorTile15,000 vector tiles
Map Matching APImatchPosition5,000 positions
createMatchedTrack5,000 positions
Routing APIcalculateRoute1,000 routes
calculateRoutePost1,000 routes
getRouteByRouteId1,000 routes
getEstimatedTimeOfArrival4,000 requests
calculateReachableAreas (sync)500 waypoints
startAndCreateReachableAreas (async)500 waypoints
startAndCreateReachableLocations500 waypoints
Routing OSM APIcalculateRoute1,000 routes
calculateReachableAreas (sync)500 waypoints
startAndCreateReachableAreas (async)500 waypoints
Matrix Routing APIcalculateMatrix (sync)1,000 matrix relations
startMatrixCalculation (async)1,000 matrix relations
Matrix Routing OSM APIcalculateMatrix (sync)1,000 matrix relations
startMatrixCalculation (async)1,000 matrix relations
EWS Road Distance APIgetRelation1,000 relations
Route Optimization APIstartOptimization60 transports
30 transports when using Optimization Premium
Route Optimization OptiFlow APIstartOptimization30 orders
Sequence Optimization APIstartAndCreateOptimizedRoute120 transports
Loading Space Optimization APIpackBins (sync)10 bins
startBinPacking (async)10 bins
Data API-No transactions charged

Please note that the error code 'GENERAL_QUOTA_EXCEEDED' is returned, if the transaction limit of your subscription is exceeded. If you need more transactions, please contact us and we will find a solution that fits best to your needs.