Developer: facts I wish I had known from scratch

[Bernd Welter]

Hi there,

as an integrator you typically start to connect to the Developer APIs with a specific setting. Every once in a while parties oversee some details in this and that lack could cause more trouble than necessary. Especially if the issues occur in production.

• Rate Limits (generics) : To protect the services from overload we defined so-called rate limits. Short term limited number of transactions per token.
  With a small starting project you might not run into this. But be prepared for a growing number of transactions with every client you add to your undelying token. As the rate limits apply per token this should be considered from scratch. Otherwise all users with a highly frequented token will experience GENERAL_RATE_LIMIT_EXCEEDED errors.
• Dynamic IPs: The services are hosted in Microsoft Azure and you should approach them via names, not via IP addresses. This is because the IPs are redispatched by Azure every once in a while. If you use IPs and Azure redispatches the domain names you will no longer reach the services (check Developer Support)
• Request limits (plan-wise) : We also defined request limits based on a token's underlying plan. This means that some tokens can compute more complex transactions than others: With a developer kit plan power you can compute big optimization scenarios. But if you user then has a productive "basic" license he might face errors where your own integrator experience was "successful".
• TOKENs : In very rare but also very important cases we may have to evaluate to disable a token (e.g. a specific token violates the agreed handling of a service). In a partner business this means: if you use the same token for all your customers and we don't know which one causes the trouble we may have to consider to block your complete customer base to protect other users. Neither you nor we want that. Therefore prepare a proper strategy!
• Asynchonous methods (11.11.2025): Take care of asynchronous calls in the proper way

Do not hesitate to get back to your technical counterpart at PTV Logistics if you have questions,

Bernd

PS: Nice to know but not ultra hard:

• Choose the proper method: Position Matching and Reverse Geocoding seem to be quite equal. Bu they are not.
• Nobody's perfect: sometimes the map data does not reflect the users desired reality due to missing data or special conditions that apply. In many cases you can benefit from the Custom Road Attributes mechanism to close the gap.
• You don't need to create client classes by yourself - we offer client classes via GIT Hub for JavaScript, .NET and Java
• Evaluate the additional data such ast TruckAttributes, historical SpeedPatterns, RestrictionZones via our vector map showcase

[Bernd Welter]

30.4.2025: added

TOKENs : In very rare but also very important cases we may have to evaluate to disable a token (e.g. a specific token violates the agreed handling of a service). In a partner business this means: if you use the same token for all your customers and we don't know which one causes the trouble we may have to consider to block your complete customer base to protect other users. Neither you nor we want that. Therefore prepare a proper strategy!

[Bernd Welter]

added "Asynchronous calls..."

Hi there,

every once in a while we face users who are running into http 429 = "too many requests".
Quite often this is caused because someone uses an asynchronous method such as

• MatrixRouting API -->startMatrixRouting
• Geocoding & Places API --> getLocationsByText
• Routing API --> startAndCreateReachableAreas
• Map Matching API --> createMatchedTrack
• Route Optimization Optiflow --> startOptimization
• and more

What these methods share is that they

• trigger a more or less complex calculation and return some Job ID
• the user is supposed to poll the progress / status of the calculation via a dedicated method
• once the status is SUCCESS / FAILED the user can gather the result (or the exception)

Now it is highly recommended to create some "waiting time" between two status polling requests, otherwise you will quickly encounter a rate limit issue.

Therefore please check this concept / turorial if you want to deal with asynchronous methods:
how-use-asynchronous-requests-ptv-developer-apis

From a meta perspective:

• Gather the job via the initial start method
• Loop as long as the job is still active (Status is PREPARING, RUNNING or QUEUEING... depends on the API)
• If you detect a running job inside the loop spend a few hundred milliseconds before you proceed with the next loop.
• Finally grab the desired output by the API's dedicated metod.

Code: Select all

Job job = client.startSomething();
do
{
   if (job.Status == active)
      Thread.sleep(500ms);
   job = client.watchProgress()
} 
while (job.Status == active) ...;
Result result = client.fetchResult(job.id);