GLS ShipIT  3.3.20
GLS ShipIT - REST services
ParcelShop search

Table of Contents

Accessing the REST for parcelshop search

The endpoints for the centrally hosted services can be obtained from your primary GLS contact and will be given with your credentials for the Service.

If you are connecting to a locally installed GLS ShipIT, you have to adapt the URL to point to the host (and port) in your network where the GLS ShipIT backend is running. E.g. https://10.10.10.10:8443//backend/rs/parcelshop

In REST, the hour format is in milliseconds since midnight with an offset of 1 hour. E.g. 28800000 corresponds to 28800000/3600000 = 8 + 1h = 09:00.

Available web service operations

getParcelShopById (F-107)

This method searches for a parcelshop with the given id.

The REST method is available at sub-path /{id} with http request method GET
Parameter Mandatory Location in RequestDescription
id TRUE path param Id of the Parcelshop which is searched.

Input validation

List of Partner ID's

If there is no prefixed Partner ID, the system will determine the Partner ID based on the ParcelShop ID entered. If the ParcelShop ID sent does not begin with one of the numerical sequences listed below, the Partner ID must be specified; otherwise, the message “ParcelShop ID not unique, please specify with Partner ID” is returned. This input help will be valid for a certain period of time. In order to be prepared for potential changes in the future and to be able to connect further countries, we recommend adapting the request to the new format (including Partner ID).

Parcelshop starting with Partner ID
276 GLS_DE
250 GLS_FR
040 GLS_AT
056 GLS_BE
208 GLS_DK
616 GLS_PL
442 GLS_LU

The REST response is an instance of eu.glsgroup.fpcs.datatypes.soap.v1.parcelshop.ParcelShop or one of the following REST faults:

Sample request

GET https://localhost:8443/backend/rs/parcelshop/GLS_DE-2761234567
[no cookies]
Request Headers:
Accept: application/glsVersion1+json, application/json
Content-Type: application/glsVersion1+json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: localhost:8443

Sample response

If the request was successful (the response is shortened to keep the sample readable):

{
"ParcelShopID": "GLS_DE-2761234567",
"Location": {
"Latitude": "50.09968",
"Longitude": "8.70346"
},
"Address": {
"Name1": "KIOSK-Shop",
"Name2": "",
"Name3": "",
"CountryCode": "DE",
"ZIPCode": "60599",
"City": "Frankfurt",
"Street": "Offenbacher Landstraߟe",
"StreetNumber": "130"
},
"WorkingDay": [{
"DayOfWeek": "MON",
"OpeningHours": {
"OpeningHours": [{
"From": 25200000,
"To": 66600000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
},
...
{
"DayOfWeek": "SAT",
"OpeningHours": {
"OpeningHours": [{
"From": 25200000,
"To": 66600000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
}
]
}

If the parcelshop does not exist:

Response headers:
HTTP/1.1 400 Bad Request
message: Parcelshop not found for id GLS_DE-2761234567
error: INVALID_PARCELSHOP_ID
Content-Length: 0
args: ["GLS_DE-2761234567","Parcelshop not found for id [\"GLS_DE-2761234567\"]"]

If a mandatory parameter (e.g. parcelShopID) was not provided:

Response headers:
HTTP/1.1 400 Bad Request
message: The Mandatory parameter parcelShopID is not set
error: MANDATORY_PARAMETER_NOT_SET
Content-Length: 0
args: ["parcelShopID"]

If an invalid value was provided (e.g. an invalid parcelShopID):

Response headers:
HTTP/1.1 400 Bad Request
message: Parcelshop not found for id xyz
error: INVALID_PARCELSHOP_ID
Content-Length: 0
args: ["xyz","Parcelshop not found for id [\"xyz\"]"]

getParcelShopsByCountryCode (F-108)

This method returns a list of Parcelshops for a specific country.
Attention: Depending on the country for which you request the parcelshops, the answer might take time and will be big. Use this service to build up a cache of parcelshops, but do not plan to call that service from any online function which requires fast response times (the parcelshop list for Germany has around 11MB of data, response time of the service is above 30 seconds).

The REST method is available at sub-path /country/{countryCode} with http request method GET
Parameter Mandatory Location in RequestDescription
countryCode TRUE path param countryCode of the Country which is searched.

Input validation

The REST response is presented as an instance of type eu.glsgroup.fpcs.datatypes.soap.v1.parcelshop.ListOfParcelShop or one of the following REST faults:

Sample request

GET https://localhost:8443/backend/rs/parcelshop/country/DE
[no cookies]
Request Headers:
Accept: application/glsVersion1+json, application/json
Content-Type: application/glsVersion1+json
Authorization: Basic dXNlcjpwYXNzd29yZA==
Host: localhost:8443

Sample response

If the request was successful (the response is shortened to keep the sample readable):

{
"ParcelShop": [{
"ParcelShopID": "GLS_DE-2761234567",
"Location": {
"Latitude": "52.48861",
"Longitude": "13.359"
},
"Address": {
"Name1": "Radio Fernsehen Klima",
"Name2": "",
"Name3": "",
"CountryCode": "DE",
"ZIPCode": "10827",
"City": "Berlin",
"Street": "Hauptstaße",
"StreetNumber": "153"
},
"WorkingDay": [{
"DayOfWeek": "MON",
"OpeningHours": {
"OpeningHours": [{
"From": 28800000,
"To": 61200000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
},
...
{
"DayOfWeek": "SAT",
"OpeningHours": {
"OpeningHours": [{
"From": 28800000,
"To": 43200000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
}
]
}, {
"ParcelShopID": "GLS_DE-2761234567",
"Location": {
"Latitude": "52.41538",
"Longitude": "13.40564"
},
"Address": {
"Name1": "1001 Kleinigkeiten",
"Name2": "",
"Name3": "",
"CountryCode": "DE",
"ZIPCode": "12349",
"City": "Berlin",
"Street": "Marienfelder Chaussee",
"StreetNumber": "145"
},
"WorkingDay": [{
"DayOfWeek": "MON",
"OpeningHours": {
"OpeningHours": [{
"From": 28800000,
"To": 61200000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
},
...
{
"DayOfWeek": "SAT",
"OpeningHours": {
"OpeningHours": [{
"From": 28800000,
"To": 46800000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
}
]
},
...

If the country code is not a valid one:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field countryCode. Value XY is not a valid value. Country (searched by GLS id, Alpha-2, Alpha-3, IOC, ISO 3166-numerical, Translations and special id) XY not found.
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["countryCode","XY","Country (searched by GLS id, Alpha-2, Alpha-3, IOC, ISO 3166-numerical, Translations and special id) XY not found."]

If the country code is not provided:

Response headers:
HTTP/1.1 400 Bad Request
message: The Mandatory parameter countryCode is not set
error: MANDATORY_PARAMETER_NOT_SET
Content-Length: 0
args: ["countryCode"]

getParcelShopsInArea (F-109)

This method searches the parcelshops within the given area.
Important: This method is deprecated. Please transform your request to the newly provided method getParcelShopinDistance.

The REST method is available at sub-path /area with http request method POST
Parameter Mandatory Location in RequestDescription
area TRUE request body The eu.glsgroup.fpcs.datatypes.soap.v1.parcelshop.Area with the request parameters.

Input validation

The response is presented as an instance of type eu.glsgroup.fpcs.datatypes.soap.v1.parcelshop.ListOfParcelShop or one of the following REST faults:

Attention: Searching over big areas will result in a slow and potentially very big response. If you plan to integrate the service in a synchronous manner, keep the search area small to ensure a quick response.

Sample request

POST https://localhost:8443/backend/rs/parcelshop/area
POST data:
{
"From": {
"Latitude": "48.57035",
"Longitude": "12.62896"
},
"To": {
"Latitude": "48.79115",
"Longitude": "9.00543"
}
}

Sample response

If the request was successful (the response is shortened to keep the sample readable):

{
"ParcelShop": [{
"ParcelShopID": "GLS_DE-2761234567",
"Location": {
"Latitude": "48.77653",
"Longitude": "12.51949"
},
"Address": {
"Name1": "Getränke Steinberger",
"Name2": "",
"Name3": "",
"CountryCode": "DE",
"ZIPCode": "94339",
"City": "Leiblfing",
"Street": "Aitrachweg",
"StreetNumber": "2"
},
"WorkingDay": [{
"DayOfWeek": "MON",
"OpeningHours": {
"OpeningHours": [{
"From": 27000000,
"To": 64800000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
},
...
{
"DayOfWeek": "SAT",
"OpeningHours": {
"OpeningHours": [{
"From": 27000000,
"To": 54000000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
}
]
}, {
"ParcelShopID": "GLS_DE-2761234567",
"Location": {
"Latitude": "48.76232",
"Longitude": "12.30146"
},
"Address": {
"Name1": "Edeka Markt",
"Name2": "Limmer E. u. A.",
"Name3": "",
"CountryCode": "DE",
"ZIPCode": "84082",
"City": "Laberweinting",
"Street": "Hofkirchen",
"StreetNumber": "110"
},
"WorkingDay": [{
"DayOfWeek": "MON",
"OpeningHours": {
"OpeningHours": [{
"From": 21600000,
"To": 43200000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
},
...
{
"DayOfWeek": "SAT",
"OpeningHours": {
"OpeningHours": [{
"From": 19800000,
"To": 39600000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
}
]
},
...

If an invalid parameter was provided:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field From.Longitude. Value 1111 is not a valid value. Longitude 1111 does not fall into the range [-180.0, 180.0].
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["From.Longitude","1111","Longitude 1111 does not fall into the range [-180.0, 180.0]."]

If a mandatory parameter was not provided:

Response headers:
HTTP/1.1 400 Bad Request
message: The Mandatory parameter Area.From.Longitude is not set
error: MANDATORY_PARAMETER_NOT_SET
Content-Length: 0
args: ["Area.From.Longitude"]

findNearestParcelShopForAddress (F-110)

This method finds the parcelshops that are nearest to a given address.
The service is limited to the next 100 parcelshops within 50 km in straight-line distance (parameter "AirlineDistance") from the given address.

The REST method is available at sub-path /address with http request method POST
Parameter Mandatory Location in RequestDescription
area TRUE request body The eu.glsgroup.fpcs.datatypes.soap.v1.parcelshop.ParcelShopSearchLocation with the request parameters.

Input validation

The response is presented as an instance of type eu.glsgroup.fpcs.datatypes.soap.v1.parcelshop.ListOfParcelShop or one of the following REST faults:

Sample request

POST https://localhost:8443/backend/rs/parcelshop/address
POST data:
{
"Street": "Marktplatz",
"StreetNumber": "52",
"CountryCode": "DE",
"ZIPCode": "94419",
"City": "Reisbach",
"Distance" : "5"
}

Sample response

If the request was successful (the response is shortened to keep the sample readable):

{
"ParcelShop": [{
"ParcelShopID": "GLS_DE-2761234567",
"Location": {
"Latitude": "48.55597",
"Longitude": "12.56134"
},
"Address": {
"Name1": "Vilstal-Bikes Baier",
"Name2": "Andreas Baier e.K.",
"Name3": "",
"CountryCode": "DE",
"ZIPCode": "84163",
"City": "Marklkofen",
"Street": "Reisbacher Str.",
"StreetNumber": "17"
},
"WorkingDay": [{
"DayOfWeek": "MON",
"OpeningHours": {
"OpeningHours": [{
"From": 28800000,
"To": 61200000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": 39600000,
"To": 43200000
}
]
}
},
...
{
"DayOfWeek": "SAT",
"OpeningHours": {
"OpeningHours": [{
"From": 28800000,
"To": 39600000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
}
],
"AirlineDistance": "5.232480979421174"
}, {
"ParcelShopID": "GLS_DE-2761234567",
"Location": {
"Latitude": "48.54448",
"Longitude": "12.52861"
},
"Address": {
"Name1": "E-W-A",
"Name2": "Inh. Werner Aumeier",
"Name3": "",
"CountryCode": "DE",
"ZIPCode": "84160",
"City": "Frontenhausen",
"Street": "Gangkofener Str.",
"StreetNumber": "30"
},
"WorkingDay": [{
"DayOfWeek": "MON",
"OpeningHours": {
"OpeningHours": [{
"From": 28800000,
"To": 61200000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": 39600000,
"To": 46800000
}
]
}
},
...
{
"DayOfWeek": "SAT",
"OpeningHours": {
"OpeningHours": [{
"From": 28800000,
"To": 39600000
}
]
},
"Breaks": {
"OpeningHours": [{
"From": -3600000,
"To": -3600000
}
]
}
}
],
"AirlineDistance": "7.934731898059682"
},
...

If a mandatory parameter was not provided:

Response headers:
HTTP/1.1 400 Bad Request
message: The Mandatory parameter parcelshopSearchLocation.ZIPCode is not set
error: MANDATORY_PARAMETER_NOT_SET
Content-Length: 0
args: ["parcelshopSearchLocation.ZIPCode"]

If an invalid parameter was provided:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field countryCode. Value XY is not a valid value. Country (searched by GLS id, Alpha-2, Alpha-3, IOC, ISO 3166-numerical, Translations and special id) XY not found.
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["countryCode","XY","Country (searched by GLS id, Alpha-2, Alpha-3, IOC, ISO 3166-numerical, Translations and special id) XY not found."]

getParcelShopinDistance (F-120)

This method returns a list of parcelshops inside the defined circle.

The REST method is available at sub-path /distance with http request method GET
Parameter Mandatory Location in RequestDescription
Latitude TRUE request body The latitude of the center of the search circle.
Longitude TRUE request body The longitude of the center of the search circle.
Distance TRUE request body The radius of the search circle.

Input validation

The response is presented as an instance of type eu.glsgroup.fpcs.datatypes.soap.v1.parcelshop.ListOfParcelShop or one of the following REST faults:

Sample request

POST https://localhost:8443/backend/rs/parcelshop/distance
POST data:
{
"Latitude": "48.784177",
"Longitude": "6.885992",
"Distance": "20"
}

Sample response

If the request was successful (the response is shortened to keep the sample readable):

{
"ParcelShop":[
{
"ParcelShopID":"GLS_DE-2761234567",
"Location":{
"Latitude":"50.90849",
"Longitude":"9.58712"
},
"Address":{
"Name1":"GLS PaketShop",
"CountryCode":"DE",
"ZIPCode":"36286",
"City":"Neuenstein",
"Street":"GLS-Germany-Straße",
"StreetNumber":"1-7"
},
"WorkingDay":[
{
"DayOfWeek":"MON",
"OpeningHours":{
"OpeningHours":[
{
"From":25200000,
"To":54000000
}
]
}
},
]
},
...
{
"ParcelShopID":"GLS_DE-2761234567",
"Location":{
"Latitude":"50.90849",
"Longitude":"9.58712"
},
"Address":{
"Name1":"GLS PaketShop22222",
"CountryCode":"DE",
"ZIPCode":"36286",
"City":"Neuenstein",
"Street":"GLS-Germany-Straße",
"StreetNumber":"1-7"
},
"WorkingDay":[
{
"DayOfWeek":"MON",
"OpeningHours":{
"OpeningHours":[
{
"From":25200000,
"To":54000000
}
]
}
},
...
]
}
]
}

If an invalid parameter was provided:

Response headers:
HTTP/1.1 400 Bad Request
message: Invalid field ParcelShopSearchDistance.Latitude. Value 1111 is not a valid value. Latitude 1111 does not fall into the range [-180.0, 180.0].
error: INVALID_FIELD_VALUE
Content-Length: 0
args: ["ParcelShopSearchDistance.Latitude","1111","Latitude 1111 does not fall into the range [-180.0, 180.0]."]

If a mandatory parameter was not provided:

Response headers:
HTTP/1.1 400 Bad Request
message: The Mandatory parameter ParcelShopSearchDistance.Latitude is not set
error: MANDATORY_PARAMETER_NOT_SET
Content-Length: 0
args: ["ParcelShopSearchDistance.Latitude"]