Skip to main content

Vietnam Two-Level Address

Get the List of Provinces​

Method 1: Retrieve Through the Country API​

Endpoint : GET https://apis.haravan.com/com/countries/704.json

Request

curl --location --request GET 'https://apis.haravan.com/com/countries/704.json' \
--header 'Authorization: Bearer ***'

Sample Response

{
  "country": {
    "carrier_shipping_rate_providers": null,
    "code": "VN",
    "id": 704,
    "name": "Vietnam",
    "price_based_shipping_rates": null,
    "provinces": [
      {
        "code": "1079",
        "country_id": 704,
        "id": 5103,
        "name": "Thành phố Hồ Chí Minh",
        "tax": null,
        "tax_name": null,
        "tax_type": null,
        "tax_percentage": null
      },
      {
        "code": "1001",
        "country_id": 704,
        "id": 5076,
        "name": "Thành phố Hà Nội",
        "tax": null,
        "tax_name": null,
        "tax_type": null,
        "tax_percentage": null
      }
    ],
    "tax": null,
    "weight_based_shipping_rates": null
  }
}

Method 2: Retrieve Through the Province API​

Endpoint : GET https://apis.haravan.com/com/countries/704/provinces.json

Request

curl --location --request GET 'https://apis.haravan.com/com/countries/704/provinces.json' \
--header 'Authorization: Bearer ***'

Sample Response

{
  "provinces": [
    {
      "code": "1079",
      "country_id": 704,
      "id": 5103,
      "name": "Thành phố Hồ Chí Minh",
      "tax": null,
      "tax_name": null,
      "tax_type": null,
      "tax_percentage": null
    },
    {
      "code": "1001",
      "country_id": 704,
      "id": 5076,
      "name": "Thành phố Hà Nội",
      "tax": null,
      "tax_name": null,
      "tax_type": null,
      "tax_percentage": null
    }
  ]
}

Get the List of District​

Endpoint : GET https://apis.haravan.com/com/provinces/{province_id}/districts.json

Example with province_id = 5103:

curl --location --request GET 'https://apis.haravan.com/com/provinces/5103/districts.json' \
--header 'Authorization: Bearer ***'

Sample Response

{
  "districts": [
    {
      "id": 7672,
      "name": "Phường Vũng Tàu",
      "code": "1026506",
      "province_id": 5103
    },
    {
      "id": 7673,
      "name": "Phường Tam Thắng",
      "code": "1026526",
      "province_id": 5103
    }
  ]
}

Using the New Address Data with Haravan APIs​

For Haravan APIs that currently use address fields:

  • Keep the existing request structure unchanged.
  • No changes are required to the object structure or field names.
  • Only update the address values to the new codes:
    • province_code
    • district_code

Field Mapping​

FieldValue to Pass
province_codeprovince.code
district_codedistrict.code

Example: Create an Order with a Shipping Address​

Example address:

  • Country: Vietnam (VN)
  • Province/Municipality: Ho Chi Minh City
    • province_code: 1079
  • Ward/Commune: Vung Tau Ward
    • district_code: 1026506

Request

curl --request POST \
  --url https://apis.haravan.com/com/orders.json \
  --header 'authorization: Bearer ***' \
  --header 'content-type: application/json' \
  --data '{
    "order": {
      "shipping_address": {
        "address1": "abc",
        "first_name": "Nguyễn Văn A",
        "country_code": "VN",
        "province_code": "1079",
        "district_code": "1026506"
      },
      "line_items": [
        {
          "variant_id": 1163757629,
          "quantity": 2
        }
      ]
    }
  }'