Essential Information

    • Data centers and clusters

      Data centers
      PTV xServer internet services are located in various Microsoft Azure data processing centres to avoid potential time delays caused by network disruptions or congestion, particularly in the case of intercontinental server requests.

      Clusters
      Each data center offers one or more Clusters. There are usually three different Clusters for each map that is hosted in the data center. These three Clusters are named test, integration and productive system. Therefore PTV xServer internet system landscape offers you a three-tier environment architecture.

      Instances
      Within one Cluster there are two or more instances with PTV xServer available. Load balancer divides the last incoming requests between different instances and therefore optimizes the performance.

    • Available PTV xServer API Versions

      API Version 1 is our established solution that is widely used in the market Your company has been a customer for a while and ha,sn't switched APls recently? Then you're most likely interested in the documentation on API Version 1

      API Version 2 is the future of PTV xServer as it's designed in a completely new framework. lt is easier to understand and as a programmer, you will benefit from improved flexibility and consistency. lf your company recently integrated PTV xServer into their software solution, is still in the middle of it or is planning an integration soon, you should look at API Version 2

    • URL Schemes

      Prefer the datacenter url
      For stateful xServer tasks
      you need a datacenter url. Stateful tasks are functions that involve multiple requests that need all to be executed on the same datacenter. For PTV xServer internet these are job requests (start/fetchCalculateTour) and all xTour-request, as xTour internally computes distance matrices that are re-used throughout multiple requests.
      If your application or middleware is at a fixed location. If your application is hosted at the same region (or even the same Azure data center), we recommend specifying url for the according region.

      Benefits of the routed URL
      Improve responsiveness for interactive clients.
      If an interactive client accesses xServer internet directly, the requests are routed to xServer internet data center with the best latency, dependent on the location of the client. Typical low-latency use cases are mapping, auto-completion geocoding and drag&drop routing.
      Domain sharding to bypass browser restrictions. The routed url also supports domain-sharding with the url scheme xserver2-(1-4)(-test).cloud.ptvgroup.com. This allows the web browser to open more connections than allowed for a single domain. This practice is typically used in map controls like OpenLayers or Leaflet to load map tiles from as many connections as possible.
      Additional availability. Even if a complete xServer datacenter would go down, the requests are be routed to a datacenter in another region.

    • Authentication

      Two different types of authentication can be used to accessing our API, depending on the technology you are using.

      HTTP Basic Authentication

      Using our service with POST requests via JSON or SOAP requires a basic authentication http header. Authorization: Basic <YOUR_CREDENTIALS>

      API key

      Using our service with RESTful calls, the xServer Internet token can send as URL parameter xtok.

      Sample

      • xserver2.cloud.ptvgroup.com/services/rest/XMap/tile/13/4238/2790?xtok=<yourtoken>
    • Three-tier environment architecture

      Test system
      Available to all users to test PTV xServer internet. The test environment is used to make new versions available or to test solutions to problems if necessary.

      Integration system (only available for API Version 1)
      You will always find the new, officially approved version of PTV xServer here. You can access the integration environment by purchasing PTV xServer internet. lt is used to develop applications. Apart from during the update phases, it is identical to the prodution system.

      Production system
      This environment contains the PTV xServer internet services for productive operations that are used by end users. PTV  ensures availability as described in the SLA concluded upon purchase.
      If a new version of PTV xServer is available, the these environments will be updated in a cycle, which is usually 2-4 week.

    • Customer hardware and software requirements

      The PTV xServer internet service offers a web service. This means that the customer is required to have an internet connection to use the service. Given that all PTV xServer services are provided via hosting, there are no minimum requirements concerning central memory, disk space or computing speed for the accessing customer system.

      There are no restrictions concerning the operating systems in use as long as it is possible to access the HTTP or HTTPS (Ports 80 and 443) via internet. PTV can and will not publish a complete list of all supported operating systems.

    • Service addresses and structure API Version 1

      You have to change the xServer internet URL and subdomain in accordance with your desired cloud service. All subdomains are based on the wildcard certificate *.cloud.ptvgroup.com and are exclusively available via HTTPS. Furthermore, the subdomain consists of three parts separated by hyphens:

      1. The name of the relevant PTV xServer service (e.g. xmap)
      2. The map cluster (e.g. eu-n)
      3. The desired system environment (e.g. test)

      Based on these details, the URL is then built as follows:

      https://<xservice>-<MapCluster>-<System>.cloud.ptvgroup.com/xservice/ws/Xservice

      You can access the PTV xServer internet Europe City map with the following url scheme:

      <service>-eu-n(-test).cloud.ptvgroup.com

      with service being either xmapxlocatexroutexmapmatch or xtour. Optionally append -test to send requests to the corresponding test system.

      For compatibility reasons, the service names ajaxmapsajaxfg and ajaxbg(1-4) are supported as well and can be used as an alias for xmap. To bybass browser restrictions with domain sharding, use ajaxbg(1-4).

    • Service addresses and structure API Version 2

      The PTV xServer or their web services are each accessible under their own URLs. You have to change the xServer internet URL and subdomain in accordance with your desired cloud service. All subdomains are based on the wildcard certificate *.cloud.ptvgroup.com and are exclusively available via HTTPS.

      You can access the PTV xServer internet Europe City map with the following url schemes:

      The routed url scheme: 

      • xserver2-<map>-(1-4)-(test).cloud.ptvgroup.com

      Datacenter url scheme: 

      • xserver2-<map>-<datacenter>-(test).cloud.ptvgroup.com