Support Portal

Welcome
Login

Enable your customers to select their preferred PUDO location v2

Introduction

 The Seven Senders PUDO locator provides a list of PUDO locations and allows you to search for the closest of them based on your location details and specified carrier(s). The information about PUDO locations can be used in your checkout to enable your customers to select their preferred PUDO location.


Changes (related to version 1)

  • Added the possibility to limit the maximum distance in meters.
  • Added information about list of temporary closing periods.
  • Added information about the validity period.
  • Added information about carrier-specific supported services.
  • Added the "Bulk Feature" which allows to get all PUDO locations for selected carrier and country.
  • Changed field name from "provider_address_line" to "address_line".
  • Improved address line conversion for both directions.
  • Limited PUDO locations up to 50 (only if searching from our database).


Authorization

The credentials for the API consist of an access key, a String provided by Seven Senders. Before starting using the API, you need to request for JWT token by executing the POST /token operation with your access key. Received JWT token should be used inside the Authorization header with the given format: Bearer YOUR_TOKEN for every further request. The JWT token is valid until the next token needs to be retrieved.



Use Cases

 To find out more about the API of our PUDO Locator, please go here

  • 1. GET locations by coordinates:

    It allows you to find the nearest PUDO locations based on your geolocation coordinates.
    In this case, you would have to provide the carrier_names[], country, latitude and longitude parameters.

    ?carrier_names[]=mondialrelay&country=FR&latitude=48.87934&longitude=2.47934
            
  • 2. GET locations by address:

    It allows you to find the nearest PUDO locations based on your given address.
    In this case, you would have to provide the carrier_names[], country and zip parameters.
    Some carriers may require also the city or street, to make the result more accurate.

    ?carrier_names[]=mondialrelay&country=FR&city=Paris&zip=75017&street=Av. des Ternes&house_no=58
            
  • 3. GET all locations:

    It allows you to get all PUDO locations for the selected carrier and country (not all carriers support this feature).
    In this case, you would have to provide the carrier_name and country parameters.

    ?carrier_name=mondialrelay&country=FR

An example response of PUDO location:

[
    {
        "carrier_name": "mondialrelay",
        "location_type": "SHOP",
        "location_id": "004694",
        "location_code": "002318317571238",
        "address": {
            "name": "Paris Telecom",
            "alternative_name": "4694 Ternes",
            "address_line": "58 Av. des Ternes",
            "street": "Av. des Ternes",
            "house_no": "58",
            "zip": "75017",
            "city": "Paris",
            "country": "FR"
        },
        "valid_from": "2020-01-01",
        "valid_to": "2026-01-10",
        "closing_periods": [
            {
                "from": "2022-08-01",
                "to": "2022-08-10",
                "reason": "holidays"
            }
        ],
        "opening_hours": {
            "monday": [
                {
                    "from": {
                        "hours": 8,
                        "minutes": 30
                    },
                    "to": {
                        "hours": 22,
                        "minutes": 30
                    }
                }
            ],
            "tuesday": [],
            "wednesday": [],
            "thursday": [],
            "friday": [],
            "saturday": [],
            "sunday": []
        },
        "coordinates": {
            "latitude": 48.87934,
            "longitude": 2.47934
        },
        "parcel_sizes": [
            "L",
            "XL"
        ],
        "distance": 0,
        "supported_services": [
            "cardboard sale",
            "case settlement"
        ],
        "additional_attributes": [
            {
                "name": "lean_locker",
                "value": "true"
            }
        ]
    },
]



Request Parameters

FieldMandatoryType
ExampleDefaultDescription
carrier_names[]YesArraymondialrelayThe list of selected carriers. In the case of two or more carriers, PUDO locations may be mixed up as they are sorted by distance. Use only in search by address or coordinates.
carrier_nameYesStringmondialrelayThe selected carrier. Use only to get all PUDO locations.
countryYes
String
FRSpecifies country in search criteria.

city

ConditionalString

Paris


Specifies city in search criteria.

zip


Conditional
String

75017

Specifies postal code in search criteria. It is required for search by address or coordinates.

street

Conditional
String
Av. des Ternes
Specifies street in search criteria.
house_noConditional
String
58
Specifies house number in search criteria. This field is combined with street.
latitudeConditional
Number48.87934Specifies the exact search location.
longitudeConditional
Number2.47934Specifies the exact search location.
max_distanceNo
Number
100025000
The maximum distance in meters between requested location and existing locations to return.
max_number_of_resultsNo
Number
1010
The maximum number of locations to return.

parcel_sizes[]


No
Array

XL


The supported parcel sizes. Some carriers have specific locations for XL parcel size.


Response Model

FieldType
ExampleDescription
carrier_nameString"mondialrelay"The selected carrier.
location_typeString"SHOP"Location type.
location_idString"004694"General location identifier which is mostly used.
location_codeString"002318317571238"Internal location identifier which is used for specific cases.
address.nameString
"Paris Telecom"The name of location.
address.alternative_nameString
"4694 Ternes"The alternative name, description or localization details.
address.address_lineString
"58 Av. des Ternes"The original address line (street and house number) provided by carrier, but sometimes it may be combined from street and house number if those fields are returned as separated. In some cases this field may supply street and house number fields after internal conversion.
address.countryString
"FR"The country of address location.

address.city

String

"Paris"

The city of address location.

address.zip

String

"75017"

The postal code of address location.

address.street

String
"Av. des Ternes"The street of address location. For some carriers this value may be extracted from address line (street and house number).
address.house_noString
"58"Specifies house number in search criteria. For some carriers this value may be extracted from address line (street and house number).
valid_fromString
"2020-01-01"The validity start date of the PUDO location. Used date format: yyyy-MM-dd.
valid_toString
"2026-01-10"The validity end date of the PUDO location. Used date format: yyyy-MM-dd.
closing_periods[].fromString
"2022-08-01"The temporary closure start date of the PUDO location. Used date format: yyyy-MM-dd.
closing_periods[].toString
"2022-08-10"The temporary closure end date of the PUDO location. Used date format: yyyy-MM-dd.
closing_periods[].reasonString
"holidays"The reason for the temporary closure of the PUDO location. This information is carrier-specific which means that it may not be unified between other carriers.
opening_hours.monday[]
opening_hours.tuesday[]
opening_hours.wednesday[]
opening_hours.thursday[]
opening_hours.friday[]
opening_hours.saturday[]
opening_hours.sunday[]

Object

{

    "from": {

        "hours": 8,

        "minutes": 30

    }

    "to": {

        "hours": 22,

        "minutes": 30

    }

}

Specifies opening hours for each day of week.

coordinates


Object

{

    "latitude": 48.87934,

    "longitude": 2.47934

}

Specifies the exact location place.

parcel_sizes

Array

["L", "XL"]

The supported parcel sizes. Some carriers have specific locations for XL shipments.
distanceNumber
0The distance in meters between requested location and existing location.
supported_servicesArray

[ "cardboard sale", "case settlement"]

List of carrier-specific supported services. They can be useful in situation where the client would like to take advantage of additional services offered by the carrier.
additional_attributesObject

{

    "name": "key",

    "value": "value"

}

The additional attributes which are provided as custom key-value pairs.




Did you find it helpful? Yes No