Comparative Rate

Preventive analysis of shipment costs

The Comparative Network endpoint allows to estimate in advance the costs of a shipment via your (active or passive) price lists, that have been saved on Gsped, such as;

  • Rental (base cost of the shipment)

  • Predictable incidental expenses

    • COD Cost

    • Insurance cost

    • FUEL

    • Remote areas or islands

    • Additional services (delivery to the floor or on Saturday, etc)

    • Charges due to oversize

    • Etc.

There are two kinds of rating:

  • ACTIVE: needs a costs analysis only related to active price lists

  • PASSIVE:costs analysis related to the price lists agreed upon with the courier in the contracting stage. This modality takes account of the ACTIVE rating to compare the shipping costs and incomes.

ComparativeRate

GET https://api.gsped.it/[INSTANCE]/RateComparativa

Path Parameters

Name
Type
Description

istanza

string

Instance to call; if not setted, redirected on shared instance.

Query Parameters

Name
Type
Description

departure_date_time

string

Datetime in YYYY-MM-DD HH:MM:SS format.

\

If not valued, the datetime is setted at the time of request. Note: If the provided date is in the past, the request will return an error!

tipo_listino

string

{attivo|passivo} Identifies the kind of rating to execute

\

PLEASE NOTE:If PASSIVE, both are returned

gls_exchange

string

{N|S} Identifies the request for EXCHANGE service to the GSped courier.

al_piano

string

{0|1} Identifies if the delivery to the floor is requested (only if the service is provided by the courier)

al_sabato

string

{0|1} Identifies if the Saturday delivery is requested (only if the service is provided by the courier)

client_id

integer

Client ID to be rated

invoiced_client_id

integer

Client ID to be rated with the ACTIVE costs in the RESELLER instances.

colli

integer

Number of parcels of the shipment

daticolli

array

Parcel size in CM | KG | CU M

\

- height

\

- width

\

- lenght

\

- weight

\

- volume

peso

number

Overall weight of the shipment (KG)

volume

number

Total volume of the shipment (M CU)

sender_addr

string

Adress of the sender

sender_city

string

City of the sender

sender_prov

string

Province code of the sender

sender_cap

string

Zip code of the sender

sender_country_code

string

ISO 2 code of the sender's country

rcpt_addr

string

Address of the recipient

rcpt_city

string

City of the recipient

rcpt_prov

string

Province code of the recipient

rcpt_cap

string

Zip code of the recipient

rcpt_country_code

string

ISO 2 code of the recipient's country

contrassegno

number

COD value

valore

number

Amount of the insurance

documenti

string

{0|1} Identifies a document shipment

preavviso_telefonico

string

{S|N} Identifies if a telephone notice is required

Headers

Name
Type
Description

accept

string

Gzip,deflate

x-api-key

string

Authentication Key given by GSped

Response

If the request is processed successfully, the system will return a JSON response formatted as shown below.

This example refers to a request made with the flag TIPO_LISTINO = passivo. This means that the response will include:

  • Passive Quotes: cost prices based on the carrier contracts you have subscribed to.

  • Active Quotes: selling prices derived from the active rate plans offered to your customers.

Each type of quote contains a detailed breakdown per carrier, structured to provide all the necessary information:

  • Carrier name

    • Service name

      • Gsped Carrier Code

      • Gsped Service Code

      • Client ID (unique Gsped customer identifier)

      • Freight (base transportation cost)

      • Surcharges (total of calculable additional costs, e.g. COD, AC Plus, etc.)

      • Total (overall shipping cost)

      • tempo_transito (shipping transit time)

      • arrivo_stimato (estimated delivery date)

{
    "passivo":
    {
        "DHL":
        {
            "Domestic Express":
            {
                "codice_corriere": "104",
                "codice_servizio": "0",
                "client_id": "1",
                "nolo": 28.55,
                "varie": 0,
                "totale": 28.55,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        },
        "TNT":
        {
            "Nazionale Express":
            {
                "codice_corriere": "2",
                "codice_servizio": "0",
                "client_id": "2",
                "nolo": 25.85,
                "varie": 0,
                "totale": 25.85,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            },
            "Nazionale 12:00 Express":
            {
                "codice_corriere": "2",
                "codice_servizio": "1",
                "client_id": "2",
                "nolo": 258.5,
                "varie": 0,
                "totale": 258.5,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        },
        "UPS":
        {
            "Nazionale UPS Standard":
            {
                "codice_corriere": "103",
                "codice_servizio": "3",
                "client_id": "3",
                "nolo": 6.07,
                "varie": 0,
                "totale": 6.07,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        },
        "GLS - contratto 1":
        {
            "Espresso Nazionale":
            {
                "codice_corriere": "101",
                "codice_servizio": "0",
                "client_id": "7",
                "nolo": 22.58,
                "varie": 0,
                "totale": 22.58,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        },
        "GLS - contratto 2":
        {
            "Espresso Nazionale":
            {
                "codice_corriere": "101",
                "codice_servizio": "0",
                "client_id": "8",
                "nolo": 22.58,
                "varie": 0,
                "totale": 22.58,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        }
    },
    "attivo":
    {
        "TNT":
        {
            "Nazionale Express":
            {
                "codice_corriere": "2",
                "codice_servizio": "0",
                "client_id": "2",
                "nolo": 26.68,
                "varie": 0,
                "totale": 26.68,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            },
            "Nazionale 12:00 Express":
            {
                "codice_corriere": "2",
                "codice_servizio": "1",
                "client_id": "2",
                "nolo": 47.5,
                "varie": 0,
                "totale": 47.5,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            },
            "Nazionale 10:00 Express":
            {
                "codice_corriere": "2",
                "codice_servizio": "2",
                "client_id": "2",
                "nolo": 52.5,
                "varie": 0,
                "totale": 52.5,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        },
        "GLS":
        {
            "Espresso Nazionale":
            {
                "codice_corriere": "101",
                "codice_servizio": "0",
                "client_id": "7",
                "nolo": 28.08,
                "varie": 0,
                "totale": 28.08,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        },
        "GLS":
        {
            "Espresso Nazionale":
            {
                "codice_corriere": "101",
                "codice_servizio": "0",
                "client_id": "8",
                "nolo": 28.08,
                "varie": 0,
                "totale": 28.08,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        }
    }
}

Some example snippets in different languages:

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.gsped.it/sandbox/RateComparativa?colli=1&contrassegno=&documenti=&peso=104&preavviso_telefonico=&rcpt_addr=via%20felrina%20sud%20172&rcpt_cap=31044&rcpt_city=Montebelluna&rcpt_country_code=IT&rcpt_prov=BG&sender_addr=VIA%20FERRANTE%20CARACCIOLO&sender_cap=24040&sender_city=LECCE&sender_country_code=IT&sender_prov=BG&tipo_listino=passivo&valore=&volume=0&invoiced_client_id=1249",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Accept: */*",
    "Cache-Control: no-cache",
    "Connection: keep-alive",
    "Host: apigsped.it",
    "accept-encoding: gzip, deflate",
    "cache-control: no-cache",
    "x-api-key: YOUR_API_KEY"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Lowest

GET https://api.gsped.it/istanza/RateComparativa/lowest

The usage of this endpoint is the same as for rateComparativa. However, the response will only include the cheapest service for each rate type (active/passive), based on the request parameters.

Example responses:

{
    "passivo": {
        "DHL": {
            "Domestic Express": {
                "codice_corriere": "104",
                "codice_servizio": "0",
                "client_id": "1",
                "nolo": 28.55,
                "varie": 0,
                "totale": 28.55,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        }
    },
    "attivo": {
        "TNT": {
            "Nazionale Express": {
                "codice_corriere": "2",
                "codice_servizio": "0",
                "client_id": "2",
                "nolo": 26.68,
                "varie": 0,
                "totale": 26.68,
                "tempo_transito": "1",
                "arrivo_stimato": "2025-09-24"
            }
        }
    }
}

Fastest

GET https://api.gsped.it/istanza/RateComparativa/fastest

The usage of this endpoint is the same as that of the rateComparativa GET, but the response returns only the fastest courier respectively for active/passive price lists as per the request made.

Example responses:

{
    "passivo": {
        "DHL - GSPED DHL": {
            "Domestic Express": {
                "codice_corriere": 104,
                "codice_servizio": "0",
                "client_id": "390",
                "nolo": 8.91,
                "varie": 1.67,
                "totale": 12.91,
                "totale_tasse": 2.33,
                "totale_no_tax": 10.58,
                "cutoff": "2025-09-16T17:00:00",
                "arrivo": "2025-09-17T23:59:00",
                "tempo_transito": "1",
                "varie_dettaglio": {
                    "fuel_surcharge": 1.67
                }
            }
        }
    }
}

Last updated