Carriyo Master List

The Carriyo Master List is a predefined list of states, cities and areas for countries where identification of addresses is complex and confusing due to lack of an addressing standard such as postal codes.

Carriyo has a predefined list of states and cities, and areas (in some cases) for these nine countries.

The master list provides merchants a consistent way of identifying states, cities and areas, and allows Carriyo to map the address data as per the requirement of different carriers, who may have their own city and area lists. The master list is also used in Carriyo for setting up automation, capacity and network rules, and reporting data by grography.

The Carriyo Master List can be downloaded here and from within the Carriyo Dashboard.

Hierarchy Levels

The Carriyo Master List is organised as follows

1. Country: Carriyo simply uses the Two-letter ISO country code to represent the country. This is already standardised and there is no reason for Carriyo to reinvent this.

2. State: A state is usually the highest level of political classification within a country. This can mean different things in different countries. For instance, in UAE, a state translates to an Emirate, where as in Saudi Arabia, a state translates to a province, and the state in Oman translates to a governorate and so on. It usually maps to administrative_area_level_1 if you reference it against the Google Maps structure

3. City: A city can represent a city or town or a village. It usually corresponds to a locality or sub_locality if you reference it against the Google Maps structure.

4. Area: An area represents a district, suburb or neighbourhood within a city. It usually corresponds to a sub_locality_1 or sub_locality_2 or neighbourhood in the Google Maps structure.

For each level in this heirarchy (except country), Carriyo defines a standard list, represented by a code, an English name and optionally a name in the local language. Carriyo also maintains the GPS coordinates for each city and area in the master list, and cross references it with Google Maps.


For countries covered by the Carriyo Master List, it is recommended to use the Carriyo standard codes when creating a shipment using the Carriyo API.

If passing the code is not possible, you may pass the name and let Carriyo automatically recgonise the code.

Please note, Carriyo may not be able correctly map address information to the carrier if the Carriyo Master List is not used.

Countries Covered

Countries covered by Carriyo Master List below:

Country City List Area List
Bahrain Cities Areas
Egypt Cities Areas
Iraq Cities Areas
Jordan Cities Areas
Kuwait Cities Areas
Lebanon Cities Areas
Oman Cities Areas
Qatar Cities Areas
Saudi Arabia Cities Areas
United Arab Emirates Cities Areas