Skip to content

The function api.get_parcelshops_by_address

This function return a list of parcelshop according to an address. It needs 3 parameters:

  • username: given by IMX
  • password: given by IMX
  • data: response data with the parcelshops

Request object

Fields List

Fields Description
Version c(1)API version Default value : "1"
country c(2)ISO 2 country code of the country research origin.L Valid countries depend on the chosen parcelsho network.
cf options.network
address1 c(60)Address1 of the research origin. The sum of the character number of address1, address2, address3 must not be greater than 60.
address2 c(60)Address2 of the research origin.
address3 c(60)Address3 of the research origin.
town c(20)Town of the research origin.
postcode c(20)Postal code of the research origin.
weight n(,0)Weight (Kg) of the parcel.
shipping_date c(10)Date of package submition in the network (JJ/MM/AAAA).
type c(10)Default value : "P"
language c(2)Default value : "P"
options Dictionary describing the different options. Contains the following fields:
.network c(40)Choice of parcelshop network.
.nb_max n(3,0)Maximum number of relay points returned.25 max.
.distance_max n(3,0)Maximum distance in km of parcelshop.40 max.d>
.latitude n(3,20)Latitude of the address in decimal degrees.
.longitude n(3,20)Longitude of the address in decimal degrees.

Response object

Fields List

Fields Description
success booleanIndicates whether the request was successful
response_quality n(1,0)Response quality,
0 : Poor qualityrresult carried out on the town, or quality not received.
1 : Medium quality result carried out on the postal code.
2 : Excellent qualityresult carried out on the address.
nb_relais n(3,0)Number of parcelshop found.
errors List of error data. Contains the following fields :
.field c(40)Name of the field generating error.We use the dot notation Exemples : country, options.networks, addressee.postcode, etc.
.message c(400)Error description.
.code c(20)Not specified.
output List of parcelshop data. Contains the following fields :
.distance n(3,0)Distance in meter between the origin of the search and the parcelshop. Relevant only if the address is localized, otherwise his default value is 0.
.options A dictionary object that contains additional information about parcelshop.
..homepage c(80)Parcelshop website.
..extra_info c(80)Additionnal information
..url_google_maps c(80)google maps url.
.details A dictionary object that contains the information of a parcelshop.
..parcelshop_id c(80)parcelshop ID.
..name c(80)Parcelshop name.
..longitude n(10,10)Parcelshop logitude.
..latitude n(10,10)Parcelshop latitude.
..address A dictionary object that contains the address data of the parcelshop.
...company c(80)Parcelshop company name.
...address1 c(80)Parcelshop address1.
...address2 c(80)Parcelshop address2.
...address3 c(80)Parcelshop address3.
...postcode c(20)Parcelshop postal code.
...town c(80)Parcelshop town.
...province c(80)Province, state of the parcelshop.
...country c(2)Parcelshop country ISO 2 Code.
...email c(80)Parcelshop E-mail.
...phone c(80)Parcelshop phone.
..holidays List of closing periods for the parcelshop. Contains the following fields :
...start datetimeStart date of the closing period of the parcelshop.
...end datetimeEnd date of the closing period of the parcelshop.
..opening_hours List of days and opening hours of the parcelshop. Contains the following fields :
...weekday c(10)Day(mon, tue, wed, thu, fri, sat, sun)
...open_morning c(80)Opening hours in the morning of the parcelshop.
...close_morning c(80)Closing hours in the morning of the parcelshop.
...open_afternoon c(80)Opening hours in the afternoon of the parcelshop.
...close_afternoon c(80)Closing hours in the afternoon of the parcelshop.

Examples

Python

python

Example of a query with the python language and the jsonrpclib module:

data = {
        "address1": "4 Route de Varigney",
        "postcode": "70800",
        "town": "Briaucourt",
        "country": "FR",
        "options" : {
            "networks" : "chronopost",
            "nb_max" : 2,
            "distance_max" : 40,
        }    
}

server = jsonrpclib.Server("https://webservice.imxpostal.fr/smc/rpc/")

resultat = server.api.get_parcelshops_by_address(USERNAME, PASSWORD, data)

pprint.pprint(resultat)

Returned result :

{
    "success": true,
    "response_quality": 2,
    "nb_relais": 2, 
    "output": [
    {
        "distance": 14492,
        "details": {
            "address": {
                "address1": "1 GRANDE RUE",
                "address2": null, 
                "address3": null, 
                "company": "",
                "country": "FR",
                "email": "",
                "phone": "",
                "postcode": "70220",
                "province": "",
                "town": "FOUGEROLLES"
                },
            "holidays": [
                {
                    "end": "2017-03-04T00:00:00",
                    "start": "2017-02-25T00:00:00"
                }
            ],
            "latitude": "47.88669680",
            "longitude": "6.405361",
            "name": "MAISON DE LA PRESSE",
            "opening_hours": [
                {
                    "close_afternoon": "19:00",
                    "close_morning": "12:15",
                    "open_afternoon": "14:30",
                    "open_morning": "14:30",
                    "weekday": "mon"
                },
                {
                "weekday": "tue",
                "close_afternoon": "19:00",
                "close_morning": "12:15",
                "open_afternoon": "14:30",
                "open_morning": "14:30",
                },                
                // etc.
            ],
            "options": {
                "extra_info": null, 
                "homepage": "", 
                "url_google_maps ": "http://maps.google.fr/maps?q=47.88669680,6.405361"
        },
"parcelshop_id": "0867S"
},
},

{
"distance": 14416,
"details": {
"address": {
"address1": "20 GRANDE RUE", "address2": "RUE PRINCIPALE EN BAS",
"address3": None, "company": "",
"country": "FR",
"email": "",
"phone": "",
"postcode": "70210",
"province": "",
"town": "VAUVILLERS"
},
"holidays": [],
"latitude": "47.9227777778",
"longitude": "6.098055555560", "name": "PROXI SUPER",
"opening_hours": [
{
"close_afternoon": "", "close_morning": "12:00", "open_afternoon": "", "open_morning": "08:30",
"weekday": "sun"
},
{
"close_afternoon": "19:00",
"close_morning": "12:15",
"open_afternoon": "16:00",
"open_morning": "08:30",
"weekday": "sat"
},
{
"close_afternoon": "19:00",
"close_morning": "12:15",
"open_afternoon": "16:00",
"open_morning": "08:30",
"weekday": "fri"
},
{
"close_afternoon": "19:00",
"close_morning": "12:15",
"open_afternoon": "16:00",
"open_morning": "08:30",
"weekday": "th"
},
{
"close_afternoon": "19:00",
"close_morning": "12:15",
"open_afternoon": "16:00",
"open_morning": "08:30",
"weekday": "wed"
},
{

"close_afternoon": "19:00",
"close_morning": "12:15",
"open_afternoon": "16:00",
"open_morning": "08:30",
"weekday": "tue"
},
{
"close_afternoon": "", "close_morning": "19:00", "open_afternoon": "", "open_morning": "14:30",
"weekday": "mon"
}
],
"options": {
"extra_info": None, "homepage": "", "url_google_maps ":
"http://maps.google.fr/maps?q=47.9227777778,6.098055555560"
},
"parcelshop_id": "5668P"
},
}
],
}

The function api.get_all_parcelshops

This function return a list of all parcelshops from the code iso2 country of network selected.

It needs 3 parameters:

  • username: given by IMX
  • password: given by IMX
  • data: payload required to play with this endpoint

Request data object:

Fields Description
country c(2)ISO 2 country code of the country research origin.Valid countries depend on the chosen parcelshop network.
options Dictionary describing the different options. Contains the following fields:
.network c(40)Choice of parcelshop network.

Response object:

Same response as the unfollowing endpoint function api.get_parcelshops_by_address

Examples:

Example 1: python with jsonrpclib module

Example code with jsonrpclib module

USERNAME = "Your username gived by IMX" 
PASSWORD = "Your password gived by IMX" 

data = {
    "country": "CZ",
    "options" : {
        "network" : "paketa_relais"
    }    
}

server = jsonrpclib.Server("https://webservice.imxpostal.fr/smc/rpc/")

resultat = server.api.get_parcelshops_by_address(USERNAME, PASSWORD, data)

pprint.pprint(resultat)

Example 2: python with requests module

import requests
from pprint import pprint

USERNAME = "gived by IMX" 
PASSWORD = "gived by IMX"

data = {
   "id":"XXX",
   "jsonrpc":"2.0",
   "method":"api.get_all_parcelshops",
   "params":[
        USERNAME,
        PASSWORD,
        {
            "country": "CZ",
            "options" : {
                "network" : "paketa_relais"
            }    
        }
    ]
}

url = "https://webservice.imxpostal.fr/smc/rpc/"

try:
    response = requests.post(url, json=data)
except Exception as e:
    raise e
else:
    result = response["output"]
    pprint(result)

api.get_parcelshop_details function

This function can be called to get parcelshop information according to its country and ID. This function is not available for the dpdbe_relais network. It requires 3 parameters: • username: given by IMX • password: given by IMX • data: Data dictionary containing your query data

Request object

Fields Description
Version c(1) (« 1 ») API version
country c(2) Parcelshop country ISO 2 code - Mandatory
parcelshop_id c(80) Unique identifier for the parcelshop - Mandatory
language c(2) default « FR »
options.network c(20) Network choice - Mandatory

Response object

Note: same as api.get_parcelshops_by_address but returns a single output rather than a list.

Fields Description
success booleanIndicates whether the request was successful
response_quality n(1,0)Response quality,
0 : Poor qualityrresult carried out on the town, or quality not received.
1 : Medium quality result carried out on the postal code.
2 : Excellent qualityresult carried out on the address.
nb_relais n(3,0)Number of parcelshop found.
errors List of error data. Contains the following fields :
.field c(40)Name of the field generating error.We use the dot notation Exemples : country, options.networks, addressee.postcode, etc.
.message c(400)Error description.
.code c(20)Not specified.
output List of parcelshop data. Contains the following fields :
.distance n(3,0)Distance in meter between the origin of the search and the parcelshop. Relevant only if the address is localized, otherwise his default value is 0.
.options A dictionary object that contains additional information about parcelshop.
..homepage c(80)Parcelshop website.
..extra_info c(80)Additionnal information
..url_google_maps c(80)google maps url.
.details A dictionary object that contains the information of a parcelshop.
..parcelshop_id c(80)parcelshop ID.
..name c(80)Parcelshop name.
..longitude n(10,10)Parcelshop logitude.
..latitude n(10,10)Parcelshop latitude.
..address A dictionary object that contains the address data of the parcelshop.
...company c(80)Parcelshop company name.
...address1 c(80)Parcelshop address1.
...address2 c(80)Parcelshop address2.
...address3 c(80)Parcelshop address3.
...postcode c(20)Parcelshop postal code.
...town c(80)Parcelshop town.
...province c(80)Province, state of the parcelshop.
...country c(2)Parcelshop country ISO 2 Code.
...email c(80)Parcelshop E-mail.
...phone c(80)Parcelshop phone.
..holidays List of closing periods for the parcelshop. Contains the following fields :
...start datetimeStart date of the closing period of the parcelshop.
...end datetimeEnd date of the closing period of the parcelshop.
..opening_hours List of days and opening hours of the parcelshop. Contains the following fields :
...weekday c(10)Day(mon, tue, wed, thu, fri, sat, sun)
...open_morning c(80)Opening hours in the morning of the parcelshop.
...close_morning c(80)Closing hours in the morning of the parcelshop.
...open_afternoon c(80)Opening hours in the afternoon of the parcelshop.
...close_afternoon c(80)Closing hours in the afternoon of the parcelshop.

Exemples

Python

Example of a query with the python language and the jsonrpclib module:

Returned result :

{
'success': True 'response_quality': 0,
'nb_relais': 1, 'output': {
'distance': 0 'details': {
'address': {
'address1': '1 GRANDE RUE', 'address2': None, 'address3': None, 'company': '',
'country': 'FR',
'email': '',
'phone': '', 'postcode': '70220', 'province': '',
'town': 'FOUGEROLLES'
},
'holidays': [
{
'end': '2017-03-04T00:00:00', 'start': '2017-02-25T00:00:00'
}
],
'latitude': '47.88669680', 'longitude': '6.405361',
'name': 'MAISON DE LA PRESSE',
'opening_hours': [
{
'close_afternoon': '12:15', 'close_morning': '12:00', 'open_afternoon': '12:00', 'open_morning': '07:00', 'weekday': 'sun'
},

{
'close_afternoon': '17:30', 'close_morning': '12:15', 'open_afternoon': '15:00', 'open_morning': '07:00', 'weekday': 'sat'
},
{
'close_afternoon': '19:00', 'close_morning': '12:15', 'open_afternoon': '14:30', 'open_morning': '06:30', 'weekday': 'fri'
},
{
'close_afternoon': '19:00', 'close_morning': '12:15', 'open_afternoon': '14:30', 'open_morning': '06:30', 'weekday': 'th'
},
{
'close_afternoon': '19:00', 'close_morning': '12:15', 'open_afternoon': '14:30', 'open_morning': '06:30', 'weekday': 'wed'
},
{
'close_afternoon': '19:00', 'close_morning': '12:15', 'open_afternoon': '14:30', 'open_morning': '06:30', 'weekday': 'tue'
},
{
'close_afternoon': '12:15', 'close_morning': '12:00', 'open_afternoon': '12:00', 'open_morning': '06:30', 'weekday': 'mon'
}
],
'options': {
'extra_info': None, 'homepage': '',
'url_google_maps ': 'http://maps.google.fr/maps?q=47.88669680,6.405361'
},
'parcelshop_id': '0867S'
},
},
}

Contact & support

For any technical question regarding setup and API use, please contact us by email at : ws.dev@imxpostal.fr.