FAQ
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, upgrade your subscription in the My Subscription App or
contact us to 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 to find a solution.
How can I generate client classes for PTV Developer APIs?
The API specification of each PTV Developer API is available as
OpenApi document of version 3 in JSON format. Each API documentation
contains a download link for its specification on the
API Reference page. An OpenAPI document can be used as a
basis for different tools that generate client classes in various
target languages. Using client classes makes it easier and more
convenient to integrate the API into an existing programming
environment. Currently, we recommend to use a patched version of
OpenAPI Generator. This patched tool supports the client
generators java (precisely Java 11),
csharp-netcore (precisely .NET Core 3.1) and
typescript-fetch. Please note that
OpenAPI Generator needs in any case a Java runtime
installation (at least Java 8).
How to use the patched tool with NPM?
The following steps describe how to use the patched tool with
the help of PTV Developer Routing API as an example:
- Put the API specification of PTV Developer Routing API as file openapi.json into the subdirectory routing of your working directory.
-
Put this content as file openapitools.json into
your working directory:
{ "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json", "spaces": 2, "generator-cli": { "version": "5.0.2", "repository": { "downloadUrl": "https://repo1.maven.org/maven2/com/github/ptv-logistics/openapi-generator-cli/5.0.2/openapi-generator-cli-5.0.2.jar" } } }
-
Put these scripts as file package.json into your
working directory:
{ "name": "@ptvgroup/developer-api-clients", "version": "1.0.0", "scripts": { "generate-dotnet": "openapi-generator-cli generate --generator-name csharp-netcore --additional-properties=targetFramework=netcoreapp3.1,useDateTimeOffset=true,optionalEmitDefaultValues=false --global-property apis,apiTests=false,models,modelTests=false,supportingFiles", "generate-typescript": "openapi-generator-cli generate --generator-name typescript-fetch --additional-properties=typescriptThreePlus=true --global-property apis,apiTests=false,models,modelTests=false,supportingFiles", "generate-java": "openapi-generator-cli generate --generator-name java --additional-properties=java8=true,dateLibrary=java8,library=native --global-property apis,apiTests=false,models,modelTests=false,supportingFiles --type-mappings=AnyType=Object" }, "devDependencies": { "@openapitools/openapi-generator-cli": "2.1.22" } }
- Execute npm install @openapitools/openapi-generator-cli in your working directory.
-
Execute one of these commands in your working directory to
generate the client classes for the target language of
your choice:
npm run generate-dotnet -- --input-spec ./routing/openapi.json --output ./routing/dotnet-client --additional-properties=packageName=PTVGroup.Developer.Clients.Routing npm run generate-typescript -- --input-spec ./routing/openapi.json --output ./routing/typescript-client npm run generate-java -- --input-spec ./routing/openapi.json --output ./routing/java-client --additional-properties=apiPackage=com.ptvgroup.developer.client.routing.api,modelPackage=com.ptvgroup.developer.client.routing.model,invokerPackage=com.ptvgroup.developer.client.routing
How to use the patched tool with Maven 3?
The following steps describe how to use the patched tool with
the help of PTV Developer Routing API as an example
using Maven 3.3.4 or above:
- Create a Maven 3 project and put the API specification of PTV Developer Routing API as file openapi.json into the subdirectory src/main/resources/routing of your project.
-
Add this plugin execution to the plugins section of your
POM and build it with Maven. Then, the patched plugin will
be fetched from the Maven Central Repository and
will generate a Maven project containing client classes
for Java 11:
<plugin> <groupId>com.github.ptv-logistics</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>5.0.2</version> <executions> <execution> <id>java-client-routing</id> <goals> <goal>generate</goal> </goals> <phase>generate-sources</phase> <configuration> <inputSpec>${project.basedir}/src/main/resources/routing/openapi.json</inputSpec> <output>${project.build.directory}/java-client/routing</output> <generatorName>java</generatorName> <generateApiTests>false</generateApiTests> <generateModelTests>false</generateModelTests> <typeMappings>AnyType=Object</typeMappings> <configOptions> <java8>true</java8> <dateLibrary>java8</dateLibrary> <library>native</library> <invokerPackage>com.ptvgroup.developer.client.routing</invokerPackage> <apiPackage>com.ptvgroup.developer.client.routing.api</apiPackage> <modelPackage>com.ptvgroup.developer.client.routing.model</modelPackage> </configOptions> </configuration> </execution> </executions> </plugin>
- For the initial generation the compilation will fail because of missing dependencies. For successful compilation, copy all dependencies of default scope from the POM in directory target/java-client/routing to your project POM or use the generated Maven project as a whole for further development.
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 upgrade your subscription in the My Subscription App or
contact us to talk about it and 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
EU - English
EU - German
US - English
How are transactions calculated?
To measure the transactions 1k packages are used as measurement unit
for the usage of different API categories.
1k transactions correspond to... | API |
1,000 individual positions or addresses | Geocoding & Places API |
15,000 data or image tiles 5,000 satellite tiles | Raster Maps API |
15,000 map tiles | Vector Maps API |
1,000 routes 500 reachable areas or locations | Routing API |
1,000 matrix relations | Matrix Routing API |
5,000 positions of a tracking request | Map Matching API |
16 requests with less than 50 transports 8 requests with less than 100 transports 4 requests with less than 200 transports 2 requests with less than 400 transports 1 request with 400 transports or more | Route Optimization API |
64 requests with less than 25 transports 32 requests with less than 50 transports 16 requests with less than 100 transports 8 requests with less than 200 transports 4 request with 500 transports or more | Sequence Optimization API |
1,000 bins | Loading Space Optimization API |
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. Note that for the Geocoding & Places API, Raster Maps API, Vector Maps API and Data API there are no request limits because the endpoints handle only single objects (map tiles, addresses or coordinates).
Find the request limits per service in the table below.
Please note that other limits apply to the free version of PTV Developer which can be seen on the activation page.
Find the request limits per service in the table below.
API | Request limit |
Geocoding & Places API | - |
Raster Maps API | - |
Vector Maps API | - |
Routing API | 25 waypoints per request |
Matrix Routing API | 250,000 matrix relations per synchronous request
4,000,000 matrix relations per asynchronous request |
Map Matching API | 16,200 positions per request |
Route Optimization API | 3,000 transports per request |
Sequence Optimization API | 500 transports per request |
Loading Space Optimization API | 2 bins / 100 items per synchronous request
100 bins / 10,000 items per asynchronous request |
Data API | - |
Please note that other limits apply to the free version of PTV Developer which can be seen on the activation page.
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 additional requests will be rejected.
Find the rate limits per service in the table below.
Find the rate limits per service in the table below.
API | Rate limit |
Geocoding & Places API | 600 requests per minute |
Raster Maps API | getSatelliteTile: 2,500 requests per minute
all other operations: 10,000 requests per minute |
Vector Maps API | 10,000 requests per minute |
Routing API | 300 requests per minute |
Matrix Routing API | calculateMatrix: 20 requests per minute
startMatrixCalculation: 50 requests per minute
getStatus: 3,000 requests per minute
all other operations: 100 requests per minute |
Map Matching API | 300 requests per minute |
Route Optimization API | startOptimization: 50 requests per minute
getOperationStatus: 3,000 requests per minute
all other operations: 100 requests per minute |
Sequence Optimization API | startAndCreateOptimizedRoute: 50 requests per minute
getOptimizedRoute: 3,000 requests per minute
all other operations: 100 requests per minute |
Loading Space Optimization API | packBins: 20 requests per minute
startBinPacking: 50 requests per minute
getStatus: 3,000 requests per minute
all other operations: 100 requests per minute |
Data API | 300 requests per minute |