[1.16.5] Points

Collecting the list of points.

Changes since version 1.7.0:

  1. Entering hard validation for all parameters of Integer, Double, List <Integer> type: in case of incorrect format or incorrect value of API parameter returns error, so far the parameter was ignored.
  2. Removing Polish translations - in the request for a possible function or possible payment method.

Points resource represents the locations in which logistic operators' services are available. Points can be self-service machines (Paczkomat Automatic Parcel Station, Laundromat) or branches, customer service points. Each of the locations offers specific services - the list of these services is returned in the response under the functions attribute.


On this page

 

Production environment:

https://api-shipx-pl.easypack24.net/v1/points

Test encironment:
You can test your implementation on a test environment available at: https://sandbox-api-pl-points.easypack24.net/v1/points


Structure

Point resource has the following attributes:

AttributeType

Description


nameString

Point ID. This is its unique name, e.g. KRA007 (for a Parcel Station)


typeArray

Table specifying the kinds of points that are in the given location. Possible types of points:

• parcel_locker - Physical automatic parcel machine and shipment handling points where a parcel machine shipment can be sent.          

• pop - Shipment handling points.     

• parcel_locker_only - Only physical automatic parcel machine.      

• parcel_locker_superpop - Shipment handling points which a parcel machine shipment can be sent to.        


status
String

Point status.


locationObject

Location object containing information on the geographic location: latitude and longitude.

Sample Location object in the JSON format: 

"latitude": 50.03988,
"longitude": 19.92485

location_type
String

Location type.


location_descriptionString

Additional location description that may make it easier to reach.


location_description_1
String

Additional description.


location_description_2
String

Additional description.


distance
Integer

Distance from the relative point location. If the relative point has not been specified takes null value.


opening_hours
String

Point opening hours


addressObject

Address object containing the points address information such as street, post-code, city.

Address object example in JSON format:

"line1": "Kapelanka 14",
"line2": null

address_details
Object

Detailed point address data

"city": "Bartoszyce",
"province": "Warmińsko-Mazurskie",
"post_code": "11-200",
"street": null,
"building_number": null,
"flat_number": null

phone_number
String

Point telephone number


payment_point_descr
String

Additional information about the point


functionsArray

Table specifying the functions offered by the point. Possible functions:

parcel=Send and collect standard parcel
parcel_send=Standard parcel send
parcel_collect=Standard parcel collect
parcel_reverse_return_send=Standard parcel reverse return to sender
standard_letter_collect=Standard letter collect
standard_letter_send=Standard letter send
allegro_parcel_collect=Allegro parcel collect
allegro_parcel_send=Allegro parcel send
allegro_parcel_reverse_return_send=Allegro parcel return to sender
allegro_letter_collect=Allegro letter collect
allegro_letter_send=Allegro letter send
allegro_letter_reverse_return_send=Allegro letter return to sender
allegro_courier_collect=Allegro courier parcel collect
allegro_courier_send=Allegro courier parcel send
allegro_courier_reverse_return_send=Allegro courier parcel return to sender
standard_courier_collect=Courier parcel collect
standard_courier_send=Courier parcel send
standard_courier_reverse_return_send=Courier parcel return to sender
air_on_airport=Send and collect baggage from machine on airport
air_outside_airport=Send and collect baggage from machine outside of airport
cool_parcel_collect=Reservation collect from cooling machine
laundry=Send and collect laundry
avizo=Avizo collect

partner_idInteger

Partner ID


is_next
Boolean

Is it a NEXT automatic parcel station


payment_available
Boolean

Availability of payment at a given point

There is a possibility of payment_available = true with payment_type = 0, it means the payment is available


payment_typeStringPayment type parameter
virtualIntegerVirtual point
recommended_low_interest_box_machines_listArrayRecommended other points nearby
location_247 BooleanIs the parcel locker available 24/7
easy_access_zoneBooleanDoes the parcel locker have an easy access zone?


Point resource in JSON format:

{  
   "href":"http://api-pl-points.easypack24.net/v1/points/KRA011",
   "name":"KRA011",
   "type":[  
      "parcel_locker"
   ],
   "status":"Operating",
   "location":{  
      "latitude":50.09103,
      "longitude":19.9299
   },
   "location_type":null,
   "location_description":"Stacja paliw Lukoil",
   "location_description_1":"",
   "location_description_2":"LUKOIL",
   "distance":null,
   "opening_hours":null,
   "address":{  
      "line1":"Opolska 9",
      "line2":"31-274 Kraków"
   },
   "address_details":{  
      "city":"Kraków",
      "province":"małopolskie",
      "post_code":"31-274",
      "street":"Opolska",
      "building_number":"9",
      "flat_number":null
   },
   "phone_number":null,
   "payment_point_descr":"Płatność internetowa PayByLink",
   "functions":[  
      "allegro_courier_collect",
      "allegro_courier_reverse_return_send",
      "allegro_courier_send",
      "allegro_letter_send",
      "allegro_parcel_collect",
      "allegro_parcel_reverse_return_send",
      "allegro_parcel_send",
      "parcel",
      "parcel_collect",
      "parcel_reverse_return_send",
      "parcel_send",
      "standard_courier_reverse_return_send",
      "standard_courier_send"
   ],
   "partner_id":0,
   "is_next":false,
   "payment_available":true,
   "payment_type":{  
      "0":"Brak obsługi płatności"
   },
   "virtual":"0",
   "recommended_low_interest_box_machines_list":null,
   "easy_access_zone": true
}


Authentication

Access to the resource does not require authentication.


List of points

List of Points retrieval, the collection supports pagination which can be found in General information.

GET /v1/points

Example request

curl -X GET https://api-shipx-pl.easypack24.net/v1/points -H 'Content-Type: application/json'

Response

{ 
  "href":"https://api-pl-points.easypack24.net/v1/points",
  "count":5363,
  "page":1,
  "per_page":25,
  "total_pages":215,
  "items":[ 
    { 
      "href":"http://api-pl-points.easypack24.net/v1/points/ADA01N",
      "name":"ADA01N",
      "type":[ 
        "parcel_locker"
      ],
      "status":"Operating",
      "location":{ 
        "latitude":51.74455,
        "longitude":22.25847
      },
      "location_type":null,
      "location_description":"Przy sklepie Groszek",
      "location_description_1":null,
      "location_description_2":"Groszek",
      "distance":null,
      "opening_hours":"24/7",
      "address":{ 
        "line1":"Kleeberga 5B",
        "line2":"21-412 Adamów"
      },
      "address_details":{ 
        "city":"Adamów",
        "province":"lubelskie",
	    "post_code":"21-412",
	    "street":"Kleeberga",
	    "building_number":"5B",
	    "flat_number":null
	  },
      "phone_number":null,
      "payment_point_descr":"Płatność internetowa PayByLink. Dostępność 24/7",
	  "functions":[ 
		"allegro_courier_collect",
		"allegro_courier_reverse_return_send",
		"parcel_reverse_return_send",
		"parcel_send",
		"standard_courier_reverse_return_send",
		"standard_courier_send"
	  ],
      "partner_id":0,
      "is_next":true,
      "payment_available":true,
      "payment_type":{ 
		"0":"Brak obsługi płatności"
	  },
      "virtual":"0",
      "recommended_low_interest_box_machines_list":null,
      "easy_access_zone": true
    },
    {...},
    {...},
  ]
}


Point details

Collecting point details.

GET /v1/points/:nazwa_punktu

Example request

curl -X GET https://api-shipx-pl.easypack24.net/v1/points/AAB001 -H 'Content-Type: application/json'

Response

HTTP/1.1 200 OK
Content-Type: application/json
{  
   "href":"http://api-pl-points.easypack24.net/v1/points/ADA01N",
   "name":"ADA01N",
   "type":[  
      "parcel_locker"
   ],
   "status":"Operating",
   "location":{  
      "latitude":51.74455,
      "longitude":22.25847
   },
   "location_type":null,
   "location_description":"Przy sklepie Groszek",
   "location_description_1":null,
   "location_description_2":"Groszek",
   "distance":null,
   "opening_hours":"24/7",
   "address":{  
      "line1":"Kleeberga 5B",
      "line2":"21-412 Adamów"
   },
   "address_details":{  
      "city":"Adamów",
      "province":"lubelskie",
      "post_code":"21-412",
      "street":"Kleeberga",
      "building_number":"5B",
      "flat_number":null
   },
   "phone_number":null,
   "payment_point_descr":"Płatność internetowa PayByLink. Dostępność 24/7",
   "functions":[  
      "allegro_courier_collect",
      "allegro_courier_reverse_return_send",
      "allegro_courier_send",
      "allegro_letter_reverse_return_send",
      "allegro_letter_send",
      "allegro_parcel_collect",
      "allegro_parcel_reverse_return_send",
      "allegro_parcel_send",
      "parcel",
      "parcel_collect",
      "parcel_reverse_return_send",
      "parcel_send",
      "standard_courier_reverse_return_send",
      "standard_courier_send"
   ],
   "partner_id":0,
   "is_next":true,
   "payment_available":true,
   "payment_type":{  
      "0":"Brak obsługi płatności"
   },
   "virtual":"0",
   "recommended_low_interest_box_machines_list":null,
   "easy_access_zone": true
}

Search criteria


ParameterType

Description

Example
nameString
Array

Searches for shipments with given name.

Searches for shipments with given names.

?name=KRA010
?name=Kra010,ADA01N

typeString
Array

Searches for shipments with given type.

Searches for shipments with given types.

?type=parcel_locker
?type=parcel_locker,pop

functionsString
Array

Searches for points with the stated function.

Searches for points with all the listed functions.

?functions=parcel
?functions=parcel,parcel_send

partner_id

Integer
Array

Searches for shipments with given partner ID.

Searches for shipments with given partner IDs.

?partner_id=1
?partner_id=1,2

is_nextBoolean

Searches for NEXT parcel locker points

?is_next=true
payment_available
Boolean

Searches by payment availability at the point

?payment_available=true
post_codeString
Array

Searches for shipments with given post code.

Searches for shipments with given post codes.

?post_code=11-111
?post_code=11-111,22-222

cityString
Array

Searches for shipments with given city.

Searches for shipments with given cities.

?city=Kraków

?city=Kraków,Warszawa


provinceString
Array

Searches for shipments with given province.

Searches for shipments with given provinces.

?province=Małopolska

?province=Małopolska,Śląsk


virtual

Integer
Array

Searches for shipments with given virtual value.

Searches for shipments with given virtual values.

?virtual=0
?virtual=1,6

updated_from
Date

Searches for points updated after the given date

If updated_to  has not been given the date cannot be earlier than 3 days before the current date

?updated_from=2018-04-24
updated_to
Date

Searches for points updated before the given date

Requires providing updated_from.

?updated_to=2018-04-26


Search by location


relative_pointString

Searches for points closest to the given location

?relative_point=52.123,19.321
relative_post_codeString

Searches for points closest to the given post code

?relative_post_code=11-111
max_distanceDouble

Searches for points in distance up to the given value from relative_point or relative_post_code 

Parameter usage requires sorting by distance.

Default value: 10000 (10km)

Maximum value 50000 (50km)

?relative_point=52.123,19.321&max_distance=10000
limitInteger

Point limiting parameter when using relative_point  or relative_post_code 

?limit=10

Result sorting

name

Sorting by point name

?sort_by=name
distance_to_relative_point

Sort by relative distance (relative_point or relative_post_code)

?sort_by=distance_to_relative_point
status

Sorting by status

?sort_by=status

Sort ordering can be set using sort_order  attribute. By default the results are sorted in an ascending order using the name field.

asc

Sorts points ascending

?sort_order=asc&sort_by=status
desc

Sorts points descending

?sort_order=desc&sort_by=status


Pagination

page

Defines the page for which the results should be returnet

?page=2
per_page

Defines the amount of points returned per page

Default: 25
Maximum:
500

?per_page=100

Filtering of returned fields


fieldsDefines the point attributes that should be returned?fields=name,type