Address Resolution

How it Works

When providing addressses during activities such as shipment creation, there are multiple ways that the address can be specified. This has the potential to lead to unexpected behaviour if the process is not well understood.

Shipments can be populated with addresses using the following methods:

  • Manually specifiying the address details in the body of the address.
  • Providing a location ID in the location_id field, in which case the location address is used.
  • Providing a location configuration ID in the location_configuration_id field.

Internally, when creating a shipment, the addresses are populated from the above in the following priority:

  • If an address has been specified in the request body, the specified address is used. The location_id must be empty, otherwise the location will be used to populate the address.
  • If a location_id is specified for an address, the address associated with the location is used.
  • If the origin or return address is unspecified, the following address resolution takes place:
  • If location_configuration_id is populated and valid, the addresses from the specified configuration are used to populate the missing origin or return address(es).
  • If a combination of parameters is present, the order of significance is as follows:
  1. Manually specified address
  2. Address attached to the location_id
  3. Address attached to the locations for the location_configuration_id

Required Fields

The destination address must always be specified, either directly or by using the location_id parameter. Generally a location_id will not be provided as a destination unless you are eg. shipping between locations within the organisation.

The origin address is also required, with the small difference that in addition to the above, it may be populated from a location configuration.

The return address will be used if supplied using anoy of the previously described methods. In the event of no return address being specified, the origin address is used.

Example Scenario

For example, if we have a request body for shipment creation as follows (only showing address part):

{
    ...
    "addresses": {
        "destination": {
            "contact": {
                "name": "Jenny Falkner",
                "email_address": "[email protected]",
                "phone_number": "+447261812509"
            },
            "address": {
                "line_1": "179 N Harbor Dr",
                "city": "Redondo Beach",
                "province": "CA",
                "post_code": "90277",
                "country_code": "US"
            }
        },
        "origin": {
          "location_id": "loc_2Kkp9sd3QzclYm1DAaMIxh5HD9C"
        },
        "location_configuration_id": "lc_2Kp4inYBJgHVzc3uUwClc9btTEB"
    }
}

The addresses will be processed as follows:

  • The destination address provided is used.
  • The origin address will be populated from the address associated with the location_id.
  • As no return address has been provided, the return address from the location_configuration_id will be used. If the location configuration ID is invalid, an error will be returned.

Address Geocoding

At several points in an order's lifecycle, it may be optimal to run distance-based calculations. As a result, geocoding is carried out on multiple address resources, including locations, when coordinates are not supplied manually.

It is thus imperative that addresses are entered in as close to a standardised format as possible when storing them, or ideally, known accurate coordinates are provided alongside the address where applicable.