Regions

Here is the current API Reference documentation. 

Sample JSON GET

URI https://api.uship.com/v2/lookups/regions

Level

The regions hierarchy is based on geography levels for data that follow several ISO standards. The "level" field value returned from the lookup identifies which geography level is being referenced. This value is the only value passed in as a depth query parameter. This table lists and describes valid values returned.

Level Code Geography-based Name Level Description
WLD World This value is for the highest parent level.
CNT Continent This value is for the seven continents of the world.
NAT Nation This value is for the countries of the world.  
PRV Province This value is for the states and provinces of the world.

Response

Field Type Description Sample 
Valid Values
TotalCount
Integer The total number of regions returned in the search.

Regions can be provinces (or states), nations (or countries), or continents. Currently, we do not support city lookups using this endpoint.

7
Items
Container Wrapper for the list of items. -
label
String The full localized name for the region. "Europe"
shortCode
String

The abbreviation for the region. This code can be used for display purposes.

  • When the item is a country, a three-letter ISO 3166-1 country code returns. The three-letter code (alpha-3) is more closely related to the country name according to the ISO standard.
  • If the item is not a country, such as when it is a state or continent, then a non-unique province or continent code is returned.
"EU"
twoLetterIsoCode
String

A two-letter ISO 3166-1 country code is returned only returned when the value is a country. The two-letter code (alpha-2) is more closely related to the general purpose code. If a geography is not at the country level, this value may be null. 

"GB"
value
String

This field value uniquely identifies a region.

The value can be

1.) passed in as a parentValue query parameter for this endpoint 

Example

The first half of the code represents the top level paired with the next level.

https://api.uship.com/v2/lookups/regions?depth=Nation&parentValue=WLD-EU

This get specifies a lookup in the hierarchy for all of the countries on the World continent of Europe. 

2.) used to create a user for registration on the uShip marketplace.

 

Examples

https://www.uship.com/mvc/register/?tid=2#carrierSelectRegions

https://www.uship.com/mvc/register/?tid=2#carrierSelectCountries

"WLD-EU"
parentValue
String This field value identifies the top-level of the depth hierarchy. The parent code identifies the body of child codes to return. "WLD"
level
String

This field value identifies which geography level is being referenced. This value is the only value passed in as a depth query parameter. 

"Continent"

Regions Hierarchy Tutorial


Let's understand how to navigate the Region hierarchy to get the unique value desired. Since it is possible to pull more than one level of region when using the lookup so understanding how to specify limitations is helpful.

 

Default | World

This endpoint and query parameter combination serves as the highest level of the hierarchy. This lookup returns the 7 continents of the world.

"https://api.uship.com/v2/lookups/regions" effectively means "https://api.uship.com/v2/lookups/regions?depth=Continent&parentValue=WLD"

Nations

To drill down into the next depth level to get a list of the world's nations, also known as countries, use this endpoint and query parameter combination:

https://api.uship.com/v2/lookups/regions?depth=Nation&parentValue=WLD-NA

Province

To drill down into the next depth level to get a list of the states or provinces within a nation or country, use this endpoint and query parameter combination:

https://api.uship.com/v2/lookups/regions?depth=Province&parentValue=NA-USA


Examples

The following examples are excerpts when the query parameters are set to the following values. Results return in alphabetical order.

 

Continents of the World

depth=Continent | parentValue=WLD
Returns the seven continents of the world.
...{	
	"label": "Asia",
	"shortCode": "AS",
	"value": "WLD-AS",
	"parentValue": "WLD",
	"level": "Continent"
},
{
	"label": "Europe",
	"shortCode": "EU",	
	"value": "WLD-EU", 
	"parentValue": "WLD",
	"level": "Continent"
},
	"label": "Oceania", 
	"shortCode": "OC",
	"value": "WLD-OC", 	
	"parentValue": "WLD",
	"level": "Continent"
}...

 

Nations or Countries of the World

depth=Nation | parentValue=WLD
Returns the countries in the world.

 

...{
	"label": "Argentina", 
	"shortCode": "ARG", 
	"twoLetterIsoCode": "AR",
	"value": "SA-ARG",
	"parentValue": "WLD-SA",
	"level": "Nation"
},
{  
	"label": "Australia",
	"shortCode": "AUS",
	"twoLetterIsoCode": "AU", 
	"value": "OC-AUS", 
	"parentValue": "WLD-OC", 
	"level": "Nation"
},
{
	"label": "United Kingdom",	
	"shortCode": "GBR",
	"twoLetterIsoCode": "GB",
	"value": "EU-GBR",
	"parentValue": "WLD-EU",
	"level": "Nation"
 }...  
   	 

 

Nations or Countries of a specific Continent

depth=Nation | parentValue=WLD-SA
Returns only countries in South America.

 

{
	"totalCount": 14,
	"items": [
		{   
			"label": "Argentina",
			"shortCode": "ARG", 
			"value": "AR", 
			"parentValue": "WLD-SA", 
			"level": "Nation"
		},
		{  
			"label": "Bolivia",
			"shortCode": "BOL",
			"twoLetterIsoCode": "BO",
			"value": "SA-BOL",
			"parentValue": "WLD-SA",	
			"level": "Nation"
		}
		  ] 
}...    

 

Provinces or States of a specific Nation

depth=Nation | parentValue=NA-USA
Returns only provinces of the United States of America.
...{
 
 	"label": "United States",
 	"shortCode": "USA",
	"twoLetterIsoCode": "US",
 	"value": "NA-USA",           (parentValue)
 	"parentValue": "WLD-NA",
 	"level": "Nation"            (depth)
 
 }

 

depth=Province | parentValue=NA-CAN
Returns only provinces of Canada.
{ 
	"totalCount": 13,
	"items": [
		{
			"label": "Alberta",   
  			"shortCode": "AB",
			"value": "CAN-AB",
			"parentValue": "NA-CAN",
			"level": "Province"
		},
		{	
			"label": "British Columbia",
			"shortCode": "BC",
			"value": "CAN-BC",
			"parentValue": "NA-CAN",
			"level": "Province"
		},
	    ]
}...