What parameters can I transfer?

Parameters are transferred to Remote Control via the URL:

http://<Web server name or IP>/mgi2023/remote/remote_control.html?<Parametername1>=<Value>&<Parametername2>=<Value> etc.

Note: During installation, the virtual directory name mgi2023 may have been changed by the administrator.

 

Important notes

  • All transferred values must be URL-encoded. For example, spaces must be replaced by %20. URL encoding functions are available in all standard programming languages.

  • The URL may be a maximum of 32,768 characters long.

  • Any values that are transferred via URL can also be transferred in an HTML form.

  • When PTV Map&Guide intranet is called up via Remote Control, the program opens in a separate window. That means the pop-up blocker for PTV Map&Guide intranet must be disabled in your browser settings.

Tip: Test transfer

You can test the transfer of the parameters via an HTML form.

After installation, you can find the test site under: http://<Web server name/IP>/mgi2023/remote/remote_test.html

Note: During installation, the virtual directory name mgi2023 may have been changed by the administrator.

 

 

The following parameters can be transferred to Remote Control:

Login data

Parameter name

Description / Values

Example

 

login

User name (required) login=user
password

Password (required)

password=secret

Language

Language (required)

Here the country code for the language that should be activated on login is passed. Permissible values are: CS, DE, EN, ES, FR, IT, NL, PL, RO, TR.

 language=EN

Routing parameter

Parameter name

Description / Values

Example

remotetype=routing

Required

Important: The remotetype parameter must be transferred with the value routing. If the parameter is missing, the transfer will fail.

remotetype=routing

action

Required

This parameter specifies whether only stop-off points should be added, or whether the route should also be calculated.

in_stationlist = insert stop-off points

routing = insert stop-off points and calculate route

action=in_stationlist

vehicle

Vehicle name (optional)

This parameter can be used to transfer a vehicle name. Please note that the vehicle name must be transferred in the language used for the login.

In the case of reference vehicles in English, this might be RF%20truck%2040t, in Spanish it might be Camión%20RF%2040%20t.

Note: As an alternative to the vehicle name, you can transfer the vehicle ID. This can be useful, for example, if the vehicle name contains special characters or spaces which cause problems when transferring the URL. When the vehicle ID is used, no URL coding is required. You can display the vehicle ID in the vehicle management use case by showing the relevant column in the vehicle list.

vehicle=RF%20truck%2040t

timestamp Sets the departure time (Unix Timestamp Format). timestamp=1628150657
clearlist

Delete list of stop-off points (optional)

1: Deletes an existing list of stop-off points before inserting stop-off points.

0 or missing: The transferred addresses are added to an existing list of stop-off points.

 clearlist=0

 

Stop-off points

Notes: At least one stop-off point must always be transferred, and route calculation is possible with two or more stop-off points. Stop-off points are automatically geocoded on import (see Note on geocoding).

Stop-off points can be transferred directly via the URL using the s<index> parameter; in this case, <index> specifies the sequence in which the stop-off points are added to the list of stop-off points – s1=1st stop-off point, s2=2nd stop-off point, and so on.

Alternatively, stop-off points can be transferred as a file using the fileurl parameter. For technical reasons, the URL linking to the file must be accessible on the same web server as Remote Control (see also http://en.wikipedia.org/wiki/Same_origin_policy).

Parameter name

Description / Values

Example

fileurl

The URL linking to the file containing the stop-off points is transferred using fileurl

fileurl=http://[webserver running the client]/remote/stations_data.txt

Note: The following parameters are only required if the value from fileurl is empty.
   
num_stations

The number of stop-off points

Specifies the number of stop-off points (s1 to s<n>) to be transferred by URL.

 num_stations=4

s<index>

 

Transferring a stop-off point

(see Constructing a stop-off point)

 

s1=places|town|DE|76131|Karlsruhe|Oststadt|Haid-und-Neu-Strasse|15|1|PTV%20Planung%20Transport%20Verkehr%20GmbH|937141|6270078|00:00|00:00|0|00:00|0|Snyder

Constructing a stop-off point

The fields for a stop-off point must be transferred in the following sequence:

<external layer name>|<internal layer name>|<country>|<zipCode>|<town>|<district>|<street>|<housenumber>|<id>|<comment>|<x-coordinate>|<y-coordinate>|<timewindow start>|<timewindow end>|<stay days>|<stay hours>|<station fuzzy radius>|name

Note: If you are using coordinates during imports, these are primarily used for geocoding. The coordinates are not compared against any addresses that you have entered. As such, you should make sure that the coordinates are correct.

 

Site

Field

Description

0

external layer name

The specification is required due to backwards compatibility reasons; the value is currently not evaluated.

1

internal layer name

The specification is required due to backwards compatibility reasons; the value is currently not evaluated.

2

country

Country code

3

zipCode

Postcode

4

town

Location

5

district

District

6

street

Street

7

housenumber

House number

8

id

The transfer of the parameter id is necessary for internal programme reasons. A value passed via the id is not evaluated and also not displayed in the programme, the content of the parameter can therefore be empty.

Tip: If an identifier for the stop-off point is to be displayed in the programme, you can pass this value via the parameter comment.

9

comment

Comment

10

x-coordinate

Coordinates in PTV Mercator format or WGS84 (decimal)

11

y-coordinate

Coordinates in PTV Mercator format or WGS84 (decimal)

12

timeslot start

Time slot start

13

timeslot end

Time slot end

14

stay days

Length of stay in days

15

stay hours 00:00

Length of stay in hours

16

stop-off point fuzzy radius

Specifies the radius in the case of a via-point
17 name Specification of a name, for example customer or company name

Export parameters

The results of the route calculation and the individual stop-off points can be returned to the system making the call in two ways:

 

 

  • Through a JSON file or XML file in a shared directory on the web server

  • Through a POST to a local URL on the client machine

     

Parameter name

Description / Values

Example

ticketid

Unique name for the routing result (required)

The ticketid is a unique string through which the external system making the call can assign a clear answer to the request.

In practice, this could be the order number from a trip management system.

ticketid=ticket0815

 
exportmode

Export mode (required)

0=Export via an HTTPS-POST to a local URL on the client machine

You can specify the local URL using the exporturl parameter. .

1=Export as file

The file is saved under the name of the ticketid in the Remote Control folder in the installation directory of PTV Map&Guide intranet.

Note: Remember that write permission is required for this directory.

Once share permission for the directory has been received, the calling system can access the file.

Note: The external system making the call is responsible for ensuring that the names of the files are unique and that different instances do not overwrite each other's files.

 exportmode=1

exporturl

 

The local URL for the return (optional)

Note: This does not need to be specified if the results are being exported as a file (exportmode=1)

The calling instance must be capable of accepting a response on this port if the return is to work. The response consists of two POST parameters: data and ticketid.

data contains the route results as a string in the selected JSON or XML format.

ticketid contains the unique identifier, which was transferred from the calling instance on request.

exporturl=https://localhost:8888

exportformat

The results of the route calculation can be output in JSON format or XML format.

 

Example for the return in XML format (exportformat=xml)

 

<ExportedRoute>

<totalDistance>972291</totalDistance>

<totalCosts>114.39</totalCosts>

<cO2e>1149.75</cO2e>

<totalTime>350089</totalTime>

</ExportedRoute>

 

Example for the return in JSON format (exportformat=json)

{

"totalDistance": 972291,

"totalCosts": 114.39,

"cO2e": 1149.75,

"totalTime": 350089

}

 

 exportformat=json

The results of the route calculation and the individual stop-off points are returned to the system making the call via a POST to a local URL on the client server: