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);

[Bernd Welter]

Links /Tools you should be aware of - bookmarks recommended - list is subject to extensions:

• Route Optimization Optiflow Forum: There's a dedicated subforum for questions all around the Route Optimization Optiflow API. We recommend to subscribe to this category to stay informed about latest news!
  • Announces new API versions
  • Keeps generic posts on top
  • Provides many articles about questions/answers, new features and describes error codes (and solutions)

  

• Request Runner: With this sample appölication you can process native JSON messages against all the different services.
  • Select the API and Method
  • Enter the body / the params
  • Send
  • For async methods: switch to progress methods and gather the updates status / final result.

  

[Bernd Welter]

Robust ENUMs...

Just a little story I want to share because some partner was running into a little mess... As you all know our API is backwards compatible by design: a request built by a certain outdated API client (e.g. 1.28 or before) will be accepted and handeled by a later version without any problem.

What can happen though is that the response contains

• new enum values for an existing enum (e.g. we added "QUEUEING" as a new status in v1.29): I recommend to use a robust style of programming that is prepared for new ENUM values. Imagine your client knows A,B,C when you implement something. Do NOT just go for

  Code: Select all

  if (myStatus==Status.A)
  { // handle condition A   }
  else if (myStatus== Status.B)
  { // handle condition B   }
  else
  { // its gotta be C   }
  

  You better go for

  Code: Select all

  if (myStatus==Status.A)
  { // handle condition A   }
  else if (myStatus== Status.B)
  { // handle condition B   }
  else
  { // handle condition C   }
  else
  { // prepare an undefined status  }
  

• new objects / collections which contain information that was placed somewhere else in the response in a previous version (e.g. we re-designed the occurence of breaks in a route with v1.35) : thats the difficult one where I cannot give a generic solution. My recommendation is:
  • Review the changes page and check for new versions. AI can help here
  • Check whether you want to benefit from a new feature and implement it if needed. Though a patch might be available within a few minutes it is definetly challenging to perform a rollout on hundreds of desktops (go for web applications / SaaS)

And so on...

As usual: get back to me if you have need for discussion in this topic