PTV Drive&Arrive | API Guide > API Description > /location/_POST

Locations

Locations are geographical locations with an unique identifier. They can have a name bound to coordinates and a dynamic set of required parameters. These parameters are needed to create trips with this location

General remarks for functions dealing with locations:

/location/ POST - create a location

This function creates a new entry in the location table. The location id may be used in trips to reference a coordinate

The function is called with method https://driveandarrive-v1.cloud.ptvgroup.com/em/location?token=<your-token>&source=<myProduct_Vx.y>.

Parameters:

Payload:

field type suggested length/ format mandatory description
name string 50 x unique name of the location for the token
coordinate.locationX double [-]##0.####### x longitude of coordinate in WGS 84
coordinate.locationY double [-]##0.####### x latitude of coordinate in WGS 84
approachingRange integer --- deprecated ---
arrivedRange integer if event position is within given radius (meter) of the location, an event with "eventType": "STATUS_STOP" and "eventSubtype": "ARRIVED" will be created automatically. default=500 (meter).
departedRange integer --- deprecated ---
address.label string 50 an identifier for the address
address.country string 3 should be iso2 or iso3 country code, e.g. DE or DEU
address.state string 100 high level partitioning of a country
address.province string 100 another level of geographical partitioning
address.postCode string 15 a post code
address.city string 100 name of the city
address.city2 string 80 name of a city district
address.street string 100 name of a street, house number may be included
address.houseNumber string 10 the house number
searchable boolean true/false x true if the location can be searched and viewed by every token. When set to false, only location token can view the location.
customDataFieldsForStop list   a list of objects which describe the expected custom data fields of a stop, when creating trips with /location/tour POST. The list is optional.
customDataFieldsForStop[i].name string 50 (x) value must be alphanumeric and must start with a lower case letter, serves as a field name in custom data of stops for this location. If the list is non-empty, then this value is mandatory for each entry in the list. The characters "," (comma) and "|" (pipe) are now allowed.
customDataFieldsForStop[i].format string 100

a regex that limits the allowed input data. This can be a fixed string ("pin") or only digits or something that matches an order id of the customer.

Please refer to this page https://msdn.microsoft.com/en-us/library/az24scfc(v=vs.110).aspx for further information.
customData{} object a JSON object with arbitrary data

example request body:

{
  "location": {
    "name": "XXXXXXXXXXXXXLOCATIONID",
    "coordinate": {
        "locationX": 13.4261419,
        "locationY": 52.5075419
    },
    "address": {
        "label": "distribution center",
        "country": "DE",
        "state": "Baden-Wuerttemberg",
        "province" : "Nordbaden",
        "postCode": "76131",
        "city": "Karlsruhe",
        "city2": "Oststadt",
        "street": "Durlacher Allee",
        "houseNumber": "80a-82b"
    },
    "searchable": true,
    "customDataFieldsForStop": [
        { 
            "name": "orderId",
            "format": "^[0-9]{10}$"
        },{
            "name": "phone",
            "format": "^[0-9]{4,20}$"
        },{
            "name": "pin"
        }
    ],
    "customData": {
        "info": "only open in the morning"
    }
  }
}

returns a JSON object:

{
  "location": {
    "locationId": "XXXXXXXXXXXXXLOCATIONID",
    "revision": 1,
    "arrivedRange": 500,
    "name": "Loc_20167794432597",
    "coordinate": {
      "locationX": 13.4261419,
      "locationY": 52.5075419
    },
    "address": {
      "label": "distribution center",
      "country": "DE",
      "state": "Baden-Wuerttemberg",
      "province" : "Nordbaden",
      "postCode": "76131",
      "city": "Karlsruhe",
      "city2": "Oststadt",
      "street": "Durlacher Allee",
      "houseNumber": "80a-82b"
    },
    "searchable": true,
    "customDataFieldsForStop": [
        { 
            "name": "orderId",
            "format": "^[0-9]{10}$"
        }, {
            "name": "phone",
            "format": "^[0-9]{4,20}$"
        }, {
            "name": "pin"
        }
    ],
    "customData": {
      "info": "only open in the morning"
    }
  }
  "responseStatus": {
    "errorCode": "ERROR" or "SUCCESS",
    "message": "description and details where applicable"
  }
}

Exceptions

validation / message error code
Location has not a coordinate LOCATION_WITHOUT_COORDINATES
Your position information has an invalid coordinate format, a geodecimal format is expected. LOCATION_WITH_INVALID_COORDINATES
Token does not exist. TOKEN_ERROR
The validation date of the token is expired. TOKEN_EXPIRED
Token is blocked. Please contact support in order to get further information. TOKEN_BLOCKED
The name for this token already exists. LOCATION_NAME_EXISTS
The list "customDataFieldsForStop" contains too many elements. TOO_MANY_CUSTOM_DATA_FIELDS
Too much custom data. Custom data is limited to 1 MByte. CUSTOMDATA_EXCEEDED
The name of a JSON property is not valid. INVALID_PROPERTY_NAME

location with searchFields in customData experimental

To be able to search stops for a location with customData (e.g. companyID, phoneNo, pin...), a location must contain searchFields defined in customData.

"customData" : {
  "searchFields" : [{
    "fieldName" : "customId"
  },{
    "fieldName" : "pin"
  },
  ...]
}

Using these searchFields, API calls /stop/search and /tour/vehicle/profile can be performed. The field values can be predefined and protected with defined format using customDataFieldsForStop.

Example location POST data:

{
  "location" : {
    "revision" : 1,
    "arrivedRange" : 500,
    "searchable" : true,
    "name" : "XXXXXXXXXXXXXLOCATIONID",
    "coordinate": {
      "locationX": 13.4261419,
      "locationY": 52.5075419
    },
    "address": {
      "label": "distribution center",
      "country": "DE",
      "state": "Baden-Wuerttemberg",
      "province" : "Nordbaden",
      "postCode": "76131",
      "city": "Karlsruhe",
      "city2": "Oststadt",
      "street": "Durlacher Allee",
      "houseNumber": "80a-82b"
    },
    "customDataFieldsForStop" : [{
      "name" : "orderId",
      "format" : "^[0-9]{10}$"
    }, {
      "name" : "phone",
      "format" :  "^[0-9]{4,20}$"
    }],
    "customData" : {
      "searchFields" : [{
          "fieldName" : "customId"
        },{
          "fieldName" : "pin"
        }]
    }
  }
}

/location/ PUT - update location

The function is called with method: https://driveandarrive-v1.cloud.ptvgroup.com/em/location?token=<your-token>&source=<myProduct_Vx.y>.

This function updates an existing entry in the location table. The location id is used to find the location.

Changing the coordinates of a location does not change existing trips or the calculation of the ETA of an existing trip. Only new trips will use the new coordinates.

The name of the location may change but must still be unique.

The given object replaces the existing one completely, i.e. any fields not set in the given object will not be saved and existing values will be removed.

Parameters:

Payload:

field type suggested length/ format mandatory description
locationId string 25 x the unique id of an existing location which belongs to the given token
name string 50 x unique name of the location for the token
revision integer 1-99999 x revision number of the current location, location can only be updated if revision number is identical at server and client side
coordinate.locationX double [-]##0.####### x longitude of coordinate in WGS 84
coordinate.locationY double [-]##0.####### x latitude of coordinate in WGS 84
arrivedRange integer if event position is within given radius (meter) of the location, an event with "eventType": "STATUS_STOP" and "eventSubType": "ARRIVED" will be created automatically. default=500 (meter).
address.label string 50 an identifier for the address
address.country string 3 should be iso2 or iso3 country code, e.g. DE or DEU
address.state string 100 high level partitioning of a country
address.province string 100 another level of geographical partitioning
adress.postCode string 15 a post code
address.city string 100 name of the city
address.city2 string 80 name of a city district
address.street string 100 name of a street, house number may be included
address.houseNumber string 10 the house number
searchable boolean true/false x true if the location can be searched and viewed by every token. When set to false, only location token can view the location.
customDataFieldsForStop list 10 a list of objects which describes the expected custom data fields of a stop, e.g. when creating "ad-hoc-trips". The list is optional.
customDataFieldsForStop[i].name string 50 (x) value must be alphanumeric and must start with a lower case letter, serves as a field name in custom data of stops for this location. If the list is non-empty then this value is mandatory for each entry in the list. The characters "," (comma) and "|" (pipe) are now allowed.
customDataFieldsForStop[i].format string 100 a regex that limits the allowed input data. This can be a fixed string ("pin"), or only digits or something that matches an order id of the customer.
customData{} object a JSON object with arbitrary data

examples request body:

{
 "location": {
    "locationId": "XXXXXXXXXXXXXLOCATIONID"
    "name": "central depot",
    "revision": 1,
    "arrivedRange": 75,
    "coordinate": {
      "locationX": 13.4261419,
      "locationY": 52.5075419
    },
    "searchable": true,
    "address": {
      "postCode": "76135",
      "city": "Karlsruhe",
      "city2": "Weststadt",
      "street": "Goethestr",
      "houseNumber": null
    },
    "customDataFieldsForStop": [
        { 
            "name": "orderId",
            "format": "^[0-9]{10}$"
        },{
            "name": "pin"
            "format": "^[0-9]{4}$"
        }
    ],
    "customData": {
      "info": "call before"
    }
 }

returns updated location with location ID and increased revision number:

{
  "location": {
    "locationId": "XXXXXXXXXXXXXLOCATIONID",
    "revision": 2,
    "arrivedRange": 75,
    "name": "central depot",
    "coordinate": {
      "locationX": 13.4261419,
      "locationY": 52.5075419
    },
    "address": {
      "postCode": "76135",
      "city": "Karlsruhe",
      "city2": "Weststadt",
      "street": "Goethestr",
      "houseNumber": null
    },
    "searchable": true,
    "customDataFieldsForStop": [
        { 
            "name": "orderId",
            "format": "^[0-9]{10}$"
        }
        {
            "name": "pin"
            "format": "^[0-9]{4}$"
        }
    ],
    "customData": {
      "info": "call before"
    }
  },
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "y1234567890y1234567890z123456789"
  }
}

Exceptions

validation / message error code
The location does not exist (for this token). LOCATION_ERROR
Your position information has an invalid coordinate format. A geodecimal format is expected. LOCATION_WITH_INVALID_COORDINATES
Location has not a coordinate. LOCATION_WITHOUT_COORDINATES
Token does not exist. TOKEN_ERROR
The validation date of the token is expired. TOKEN_EXPIRED
Token is blocked. Please contact support in order to get further information. TOKEN_BLOCKED
The name for this token already exists. NAME_EXISTS
The list "customDataFieldsForStop" contains too many elements. TOO_MANY_CUSTOM_DATA_FIELDS
Too much custom data. Custom data is limited to 1 MByte. CUSTOMDATA_EXCEEDED
The name of a JSON property is not valid. INVALID_PROPERTY_NAME
Existing location revision does not match with the update revision. WORKING_COPY_IS_OUT_OF_DATE

/location/{ID} DELETE - delete location

The function is called with method https://driveandarrive-v1.cloud.ptvgroup.com/em/location/<your-locationId>?token=<your-token>&source=<myProduct_Vx.y>.

This function deletes an existing entry in the location table. The location id is used to find the location.

Parameters:

Returns:

Exceptions

validation / message error code
Location-ID not valid. Location-ID should be a 25-digit, case-sensitive, alphanumeric identifier of a location. LOCATION_ID_INVALID
Location does not exist. LOCATION_ERROR
Token does not exist. TOKEN_ERROR
The validation date of the token is expired. TOKEN_EXPIRED
Token is blocked. Please contact support in order to get further information. TOKEN_BLOCKED

/location/ GET - get locations

The function is called with method https://driveandarrive-v1.cloud.ptvgroup.com/em/location?token=<your-token>&startIndex=<startIndex>&itemsPerPage=<itemsPerPage>&sortOrder=<attribute1|ASC/DESC,atrribute2|ASC/DESC....>.

This function returns locations of the given token.

Parameters:

ExtKeyValueSearch examples

	{key:location.name,value:Cargoclix_} or
	{key:location.name,value:Cargoclix_},{key:location.address.city,value:arlsr} or
	{key:location.address.city,value:^Karls}

returns a JSON object:

{
  "locations": "an array of JSON objects containing all the locations that belong to the given token and fit into the paging criteria",
  "currentItemCount": "the returned items count",
  "itemsPerPage": "the given itemsPerPage of the query",
  "startIndex": "the give index of the query",
  "totalItems": "the maximum available entries",
  "responseStatus": {
    "errorCode": "ERROR" or "SUCCESS",
    "message": "description and details where applicable"
  }
}

example response body:

{
  "locations": [
    {
        "locationId": "x123456789y123456789z1234"
        "name": "central depot",
        "revision": 1,
        "arrivedRange": 75,
        "address": {
            "postCode": "76135",
            "city": "Karlsruhe",
            "city2": "Weststadt",
            "street": "Goethestr",
            "houseNumber": null
        },
        "searchable": true,
        "customDataFieldsForStop": [
            { 
                "name" : "pin"
            }
        ],
        "customData": {
            "SMTAddressInfo": "call before",
            "SMTIndicator": 153
        }
    },
    {
        "locationId": "x123456789y123456789z5678"
        "name": "depot",
        "revision": 1,
        "arrivedRange": 75,
        "coordinate": {
            "locationX": 13.4261419,
            "locationY": 52.5075419
        },
        "address": {
            "label": "distribution center",
            "country": "DE",
            "state": "Baden-Wuerttemberg",
            "province" : "Nordbaden",
            "postCode": "76131",
            "city": "Karlsruhe",
            "city2": "Oststadt",
            "street": "Durlacher Allee",
            "houseNumber": "80a-82b"
        },
        "searchable": true,
        "customDataFieldsForStop": [
            { 
                "name": "orderId",
                "format": "^DN[0-9]{10}"
            },
            {
                "name": "phone",
                "format": "[0-9]{4-20}"
            },
            {
                "name": "products"
            }
        ],
        "customData": {
            "info": "only open in the morning"
        }
    }
  ],
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "x1234567890y1234567890z123456789"
  }
}

Exceptions

validation / message error code
Token does not exist. TOKEN_ERROR
The validation date of the token is expired. TOKEN_EXPIRED
Token is blocked. Please contact support in order to get further information. TOKEN_BLOCKED
Exceeded max itemsPerPage size of 500. LOCATION_ITEMS_PER_PAGE_LIMIT_EXCEEDED
itemsPerPage is missing or value must be greater than zero. INVALID_ITEMSPERPAGE
The sort parameter is invalid. Expected format is "key|ASC" or "key|DESC". INVALID_SORT_PARAMETER

/location/{ID} GET - get a single location by id (find by id)

The function is called with method https://driveandarrive-v1.cloud.ptvgroup.com/em/location/{ID}?token=<your-token>.

Returns a single location object identified by the given id.

Parameters:

returns a JSON object:

{
  "location": "the requested location belonging to the given token",
  "responseStatus": {
    "errorCode": "ERROR" or "SUCCESS",
    "message": "description and details where applicable"
  }
}

Exceptions

validation / message error code
Location-ID is not valid. Location-ID should be a 25-digit, case-sensitive, alphanumeric identifier of a location. LOCATION_ID_INVALID
Location (for this token) does not exist. LOCATION_ERROR
Token does not exist. TOKEN_ERROR
The validation date of the token is expired. TOKEN_EXPIRED
Token is blocked. Please contact support in order to get further information. TOKEN_BLOCKED
Exeeded maximum itemsPerPage size of 500. LOCATION_ITEMS_PER_PAGE_LIMIT_EXEEDED

/location/arrivals/{ID}/ GET - get stop and ETA information for location

The function is called with method https://driveandarrive-v1.cloud.ptvgroup.com/em/location/arrivals/{ID}?token=<your-token>&from=<earliestDateOfEtas>&until=<latestDateOfEtas>&startIndex=<startIndex>&itemsPerPage=<itemsPerPage>&sortOrder=<attribute1|ASC/DESC,attribute2|ASC/DESC,....>

This function returns stops which use a reference to the given location id. The location id must belong to the token. The trips on the other side need not belong to the token. If the trip owner knows the location he has been informed by the location owner offline. So it can be assumed that they agreed to exchange data.

Parameters:

Returns:

Remarks:

{
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "x1234567890y1234567890z123456789"
  },
  "arrivals": [
    {
      "stop": {
        "coordinate": {
          "locationX": 8.328665,
          "locationY": 48.981243
        },
        "earliestArrivalTime": "2015-11-19T08:00:00.0000000+01:00",
        "latestDepartureTime": "2015-11-19T09:00:00.0000000+01:00",
        "serviceTimeAtStop": 3600,
        "useServicePeriodForRecreation": true,
        "weightWhenLeavingStop": 0,
        "stopPositionInTour": 0,
        "customData": {
          "user": "customer"
        },
        "locationId": "XXXXXXXXXXXXXXXXXXXXXXXXX",
        "scemid": "X9X9X9X9X9",
        "source": "caller",
        "emCreateTime": "2015-11-19T12:43:41.3209830+01:00"
      },
      "etaInfo": {
        "plannedETA": "2015-11-19T08:00:00.0000000+01:00",
        "eta": "2015-11-19T08:00:00.0000000+01:00",
        "etaSource": "PLANNED_TOUR_ETA",
        "relatedTime": "2015-11-19T12:43:41.4216287+01:00"
      }
    },
    {
      "stop": {
        "coordinate": {
          "locationX": 8.328665,
          "locationY": 48.981243
        },
        "earliestArrivalTime": "2015-11-19T09:00:00.0000000+01:00",
        "latestDepartureTime": "2015-11-19T10:00:00.0000000+01:00",
        "serviceTimeAtStop": 3600,
        "useServicePeriodForRecreation": true,
        "weightWhenLeavingStop": 0,
        "stopPositionInTour": 0,
        "customData": {
          "user": "customer"
        },
        "locationId": "XXXXXXXXXXXXXXXXXXXXXXXXX",
        "scemid": "X9X9X9X9X9",
        "source": "caller",
        "emCreateTime": "2015-11-19T12:43:43.7651602+01:00"
      },
      "etaInfo": {
        "plannedETA": "2015-11-19T09:00:00.0000000+01:00",
        "eta": "2015-11-19T09:00:00.0000000+01:00",
        "etaSource": "PLANNED_TOUR_ETA",
        "relatedTime": "2015-11-19T12:43:43.7796194+01:00"
      },
      "status": "ARRIVED" // only if exists
    },
    {
      "stop": {
        "coordinate": {
          "locationX": 8.328665,
          "locationY": 48.981243
        },
        "earliestArrivalTime": "2015-11-19T10:00:00.0000000+01:00",
        "latestDepartureTime": "2015-11-19T11:00:00.0000000+01:00",
        "serviceTimeAtStop": 3600,
        "useServicePeriodForRecreation": true,
        "weightWhenLeavingStop": 0,
        "stopPositionInTour": 0,
        "customData": {
          "user": "customer"
        },
        "locationId": "XXXXXXXXXXXXXXXXXXXXXXXXX",
        "scemid": "X9X9X9X9X9",
        "source": "caller",
        "emCreateTime": "2015-11-19T12:43:45.8242693+01:00"
      },
      "etaInfo": {
        "plannedETA": "2015-11-19T10:00:00.0000000+01:00",
        "eta": "2015-11-19T10:00:00.0000000+01:00",
        "etaSource": "CALCULATE_POS_ETA",
        "relatedTime": "2015-11-19T12:43:45.8373018+01:00"
      }
    },
    {
      "stop": {
        "coordinate": {
          "locationX": 8.328665,
          "locationY": 48.981243
        },
        "earliestArrivalTime": "2015-11-19T11:00:00.0000000+01:00",
        "latestDepartureTime": "2015-11-19T12:00:00.0000000+01:00",
        "serviceTimeAtStop": 3600,
        "useServicePeriodForRecreation": true,
        "weightWhenLeavingStop": 0,
        "stopPositionInTour": 0,
        "customData": {
          "user": "customer"
        },
        "locationId": "XXXXXXXXXXXXXXXXXXXXXXXXX",
        "scemid": "X9X9X9X9X9",
        "source": "caller",
        "emCreateTime": "2015-11-19T12:43:47.8710667+01:00"
      },
      "etaInfo": {
        "plannedETA": "2015-11-19T11:00:00.0000000+01:00",
        "eta": "2015-11-19T11:00:00.0000000+01:00",
        "etaSource": "CALCULATE_POS_ETA",
        "relatedTime": "2015-11-19T12:43:47.8840758+01:00"
      }
    },
    {
      "stop": {
        "coordinate": {
          "locationX": 8.328665,
          "locationY": 48.981243
        },
        "earliestArrivalTime": "2015-11-19T13:00:00.0000000+01:00",
        "latestDepartureTime": "2015-11-19T14:00:00.0000000+01:00",
        "serviceTimeAtStop": 3600,
        "useServicePeriodForRecreation": true,
        "weightWhenLeavingStop": 0,
        "stopPositionInTour": 0,
        "customData": {
          "user": "customer"
        },
        "locationId": "XXXXXXXXXXXXXXXXXXXXXXXXX",
        "scemid": "X9X9X9X9X9",
        "source": "caller",
        "emCreateTime": "2015-11-19T12:43:49.9191188+01:00"
      },
      "etaInfo": {
        "plannedETA": "2015-11-19T13:00:00.0000000+01:00",
        "eta": "2015-11-19T13:00:00.0000000+01:00",
        "etaSource": "CALCULATE_POS_ETA",
        "relatedTime": "2015-11-19T12:43:49.9311303+01:00"
      }
    }
  ],
  "currentItemCount": 5,
  "itemsPerPage": 50,
  "startIndex": 0,
  "totalItems": 5
}

Exceptions

validation / message error code
The location does not exist (for this token). LOCATION_ERROR
Location-ID not valid. Location should be a 25-digit, case-sensitive, alphanumeric identifier of a location. LOCATION_ID_INVALID
The start of the interval is after the end. INTERVAL_FROM_AFTER_UNTIL
Token does not exist. TOKEN_ERROR
The validation date of the token is expired. TOKEN_EXPIRED
Token is blocked. Please contact support in order to get further information. TOKEN_BLOCKED
Exceeded maximum itemsPerPage size of 500. LOCATION_ITEMS_PER_PAGE_LIMIT_EXCEEDED
ItemsPerPage missing or value must be greater than zero. INVALID_ITEMSPERPAGE
The sort parameter is invalid. Expected format is "key|ASC" or "key|DESC". INVALID_SORT_PARAMETER

Note: Sorting on Arrivals is currently allowed only on following fields:

/location/tour POST - create a single stop tour

The function is called with method https://driveandarrive-v1.cloud.ptvgroup.com/em/location/tour/

The function creates a trip with a single stop where the stop will use a location id to identify the position. This function does not take a token as parameter as most of the other functions because it may be used by clients without tokens. The trip creation is paid by the location owner.

If the location contains a list of custom data field descriptions then this method checks whether the provided custom data contains these fields and whether the field values match the regular expression of the custom data fields descriptions.

Parameters:

Payload:

example request body:

{
  "tour": {
    "stops": [
      {
        "locationId": "XXXXXXXXXXXXXLOCATIONID",
        "earliestArrivalTime": "2015-10-27T10:35:00+01:00",
        "latestDepartureTime": "2015-10-27T10:45:00+01:00",
        "customData": {
          "orderId": "0123456789",
          "phone": "072196510000"
        }
      }
    ],
    "vehicle": {
      "vehicleProfileID": "mg-truck-40t"
    }
  }
}

Returns:

Exceptions

validation / message error code
For a single stop trip exactly one stop must be provided. STOP_COUNT_INVALID
The stop must contain a location id. LOCATION_ID_MISSING
The location id of the stop is unknown. LOCATION_ERROR
The custom data provided does not match. CUSTOM_DATA_MISMATCH
The list contains too many elements. TOO_MANY_CUSTOM_DATA_FIELDS
Too much custom data. Custom data is limited to 1 MByte. CUSTOM_DATA_TOO_LARGE
The name of a JSON property is not valid. INVALID_PROPERTY_NAME
Driver count > 1 not supported. DRIVER_NOT_ALLOWED
Profile not existing. You should use one of the predefined profiles. NO_SUCH_VEHICLEPROFILE
The size of your tour object is too large. Please reduce the number of stops of your tour or remove customData if existing. TOUROBJECT_SIZE_EXCEEDED
Time of stop is invalid TIME_OF_STOP_MISSING
latestDepartureTime of stop before earliestArrivalTime TIME_OF_STOP_INVALID
Maximum allowed tour duration of n days from [YYYY-MM-DDThh:mm:ss.0000000+01:00] has been exceeded. TOUR_DURATION_EXCEEDED

Remarks:

Single stop tour to a location with searchFields in customData experimental

Using these searchFields in API calls /stop/search and /tour/vehicle/profile to search stops to a location, a single stop tour must have searchFields defined in customData. The field values must match the format defined in customDataFieldsForStop of the location.

Example /location/tour/ POST data:

{
  "tour": {
    "stops": [
      {
        "locationId": "XXXXXXXXXXXXXLOCATIONID",
        "earliestArrivalTime": "2016-10-27T10:35:00+01:00",
        "latestDepartureTime": "2016-10-27T10:45:00+01:00",
        "customData": {
          "orderId": "0123456789",
          "phone": "072196510000",
          "searchFields": [{
              "fieldName" : "customId",
              "fieldValue": "01234567"
            },{
              "fieldName" : "pin",
              "fieldValue": "0123"
          }]
        }
      }
    ],
    "vehicle": {
      "vehicleProfileID": "mg-truck-40t"
    }
  }
}

/location/proximity/ GET - get locations in proximity of a coordinate

To search locations in proximity from given coordinate following API call can be made https://driveandarrive-v1.cloud.ptvgroup.com/em/location/proximity?X=<coordinate-x>&Y=<coordinate-y>&Range=<range-in-m>&SortOrder=<fieldName|sortOrder>&ItemsPerPage=<maxItem>&StartIndex=0&Token=<your-token>&Source=<your-src>

parameters:

returns:

Example response:

{
  "proximityResults": [
    {
      "location": {
        "locationId": "XXXXXXXXXXXXXLOCATIONID",
        "revision": 1,
        "arrivedRange": 75,
        "searchable": true,
        "name": "arrivals9",
        "coordinate": {
          "locationX": 8.111,
          "locationY": 48.111
        },
        "address": {
          "label": "LabelA",
          "country": "country",
          "state": "state",
          "province": "Province",
          "postCode": "PostCode",
          "city": "city",
          "city2": "city2",
          "street": "street",
          "houseNumber": "42"
        },
        "customDataFieldsForStop": [
          {
            "name": "Auftragsnr"
          },
          {
            "name": "Pin"
          }
        ]
      },
      "distance": 14846
    },
    {
      "location": {
        "locationId": "XXXXXXXXXXXXXXXXXXXXXXXX1",
        "revision": 1,
        "arrivedRange": 75,
        "searchable": true,
        "name": "arrivals8",
        "coordinate": {
          "locationX": 8.111,
          "locationY": 48.111
        },
        "address": {
          "label": "LabelA",
          "country": "country",
          "state": "state",
          "province": "Province",
          "postCode": "PostCode",
          "city": "city",
          "city2": "city2",
          "street": "street",
          "houseNumber": "42"
        },
        "customDataFieldsForStop": [
          {
            "name": "Auftragsnr"
          },
          {
            "name": "Pin"
          }
        ]
      },
      "distance": 14846
    },
    {
      "location": {
        "locationId": "XXXXXXXXXXXXXXXXXXXXXXXX2",
        "revision": 1,
        "arrivedRange": 75,
        "searchable": true,
        "name": "arrivals7",
        "coordinate": {
          "locationX": 8.111,
          "locationY": 48.111
        },
        "address": {
          "label": "LabelA",
          "country": "country",
          "state": "state",
          "province": "Province",
          "postCode": "PostCode",
          "city": "city",
          "city2": "city2",
          "street": "street",
          "houseNumber": "42"
        },
        "customDataFieldsForStop": [
          {
            "name": "Auftragsnr"
          },
          {
            "name": "Pin"
          }
        ]
      },
      "distance": 14846
    }
  ],
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "00000000000000000000000000000000"
  },
  "currentItemCount": 3,
  "itemsPerPage": 50,
  "startIndex": 0,
  "totalItems": 3
}

Exceptions

validation / message error code
Token does not exist. TOKEN_ERROR
The validation date of the token is expired. TOKEN_EXPIRED
Token is blocked. Please contact support in order to get further information. TOKEN_BLOCKED
The sort parameter is invalid. Expected format is "key|ASC" or "key|DESC". INVALID_SORT_PARAMETER
Exceeded maximum itemsPerPage size of 500. LOCATION_ITEMS_PER_PAGE_LIMIT_EXCEEDED
Range not valid. Value must be greater or equal zero. INVALID_RANGE
Invalid start index. Value must be greater or equal zero. INVALID_START_INDEX
ItemsPerPage missing or value must be greater than zero. INVALID_ITEMSPERPAGE

 

 

© 2022 PTV Planung Transport Verkehr GmbH | Imprint

Get in Contact