# Advanced Address Types

# Introduction

In version 1, we introduce the concept of origin and destination for orders. Integrator can now select types explicitly which makes validation easier and reduces the chance of errors.

This approach creates a more robust system that simplifies debugging, improves consistency across different regions, and enhances scalability for future requirements.

# Address Types

We support multiple delivery or shipping types based on the origin and destination. Each origin and destination type is pre-defined, and integrators must choose one from these available options.

Shipping types affect how addresses are formatted. Each type has a specific way of writing the address to ensure accuracy and consistency.

# Example

As you see in the example below, The order creation has well structured format. You will learn more on this by Next chapter.

{
  "reference": "ORD-654789123",

  "origin_type":"branch",
  "origin": {
    "branch": "66ec0dd019f1110031e6ffc0"
  },

  "destination_type":"kuwait_components",
  "destination": {
    "contact": {
      "name": "zakaria",
      "phone": "+96566473829"
    },
    "address_components": {
      "area": "Abdullah Mubarak Al-Sabah",
      "block": "5",
      "street": "St 503",
      "building": "123"
	  },
    "floor": "2", // optional
    "apartment": "12A", // optional
    "instructions": "Put it in front of door and ring the bell" // optional
  },

  "payment": {
    "amount": "7.000",
    "type": "paid"
  }
}

# Origin

We offer two types of origin: branch and location_components.

# Branch Type

Use this when the pickup location is a pre-registered branch in your Armada account.

{
  // ...
  "origin_type": "branch",
  "origin" :{
    "branch": "your-branch-reference"
  }
  // ...
}

# Location Components Type

Use this when you want to specify a custom pickup location with geographic coordinates.

{
  // ...
  "origin_type": "location_components",
  "origin": {
    "address_components": {
      "location": {
        "latitude": 29.3140728,
        "longitude": 48.021550
      },
      "floor": "2", // optional
      "apartment": "5" // optional
    },
    "contact": {
      "name": "Ahmed Ali",
      "phone": "+212680985566"
    }
  }
  // ...
}

# Destination

The destination accepts the following types:

location_components
kuwait_components
bahrain_components
ksa_components
ksa_short_components

# Location Components Type

For global shipping or delivery, we support using "location_components" as a valid address type.

{
  // ...
  "destination_type": "location_components",
  "destination" :{
    "contact": {
      "name": "zakaria",
      "phone": "+96566473829"
    },
    "address_components": {
      "first_line": "123 Main St", // optional (human readable helper for drivers)
      "location": {
        "latitude": 29.355069903470575,
        "longitude": 47.80469652165224
      }
    },
    "floor": "2", // optional
    "apartment": "12A", // optional
    "instructions": "Put it in front of door and ring the bell" // optional
  }
  // ...
}

# Kuwait Components Type

{
  // ...
  "destination_type": "kuwait_components",
  "destination" :{
    "contact": {
      "name": "zakaria",
      "phone": "+96566473829"
    },
    "address_components": {
      "area": "Abdullah Mubarak Al-Sabah",
      "block": "5",
      "street": "St 503",
      "building": "123"
    },
    "floor": "2", // optional
    "apartment": "12A", // optional
    "instructions": "Put it in front of door and ring the bell" // optional
  }
  // ...
}

# Bahrain Components Type

{
  // ...
  "destination_type": "bahrain_components",
  "destination" :{
    "contact": {
      "name": "zakaria",
      "phone": "+96566473829"
    },
    "address_components": {
      "area": "Adliya",
      "block": "338",
      "street": "Road 2819",
      "building": "150"
    },
    "floor": "2", // optional
    "apartment": "12A", // optional
    "instructions": "Put it in front of door and ring the bell" // optional
  }
  // ...
}

# Ksa Components Type

{
  // ...
  "destination_type": "ksa_components",
  "destination" :{
    "contact": {
      "name": "zakaria",
      "phone": "+96566473829"
    },
    "address_components": {
      "city": "Al Olaya",
      "street": "King Fahd Road",
      "district": "Al Olaya District",
      "building": "456"
	  },
    "floor": "2", // optional
    "apartment": "12A", // optional
    "instructions": "Put it in front of door and ring the bell" // optional
  }
  // ...
}

# Ksa Short Components Type

{
  // ...
  "destination_type": "ksa_short_components",
  "destination" :{
    "contact": {
      "name": "zakaria",
      "phone": "+96566473829"
    },
    "address_components": {
      "short_address":"RFNC7220"
    },
    "floor": "2", // optional
    "apartment": "12A", // optional
    "instructions": "Put it in front of door and ring the bell" // optional
  }
  // ...
}