Locations for Outline-based Maps in JavaScript

How to specify country codes, names, and US states for outline-based maps

Plotly Studio: Transform any dataset into an interactive data application in minutes with AI. Try Plotly Studio now.

Locations for Outline-based Maps

With outline-based maps, you can visualize data for specific regions using the locations and locationmode parameters.

The following map types in Plotly.js support these parameters:

choropleth - color regions based on data values
scattergeo - show markers at geographic locations

The locations parameter accepts region identifiers and the locationmode parameter controls how those identifiers are interpreted:

'ISO-3' - three-letter ISO country codes (for example, 'USA', 'CAN', 'GBR')
'USA-states' - two-letter US state abbreviations (for example, 'CA', 'TX', 'NY')
'country names' - full country names (for example, 'United States')

locationmode: 'ISO-3'

Set locationmode: 'ISO-3' to use three-letter ISO country codes in locations.

var data = [{
    type: 'choropleth',
    locations: ['USA', 'CAN', 'MEX', 'BRA', 'RUS'],
    locationmode: 'ISO-3',
    z: [100, 85, 72, 95, 68],
    colorscale: 'Viridis'
}];

var layout = {
    title: 'Choropleth with ISO-3 Country Codes',
    geo: {
        projection: {
            type: 'natural earth'
        }
    }
};

Plotly.newPlot('myDiv', data, layout);

Supported ISO Codes

The following ISO codes are supported when locationmode='ISO-3':

Codes marked ^† are only present in the higher-resolution map data. Since geo.resolution defaults to 110, plotting one of those locations also needs resolution: 50 on the geo subplot, or the location is skipped and nothing is drawn for it.

Rows marked (grouped with ...) are territories the map data draws inside another country's feature, listed here so the code is easy to find. Plotting one shades that whole country, and the territory name itself is not accepted as a value for locationmode: 'country names'.

Name	ISO Code
Afghanistan	AFG
Aksai Chin	XAC
Åland Islands	ALA
Albania	ALB
Algeria	DZA
American Samoa	ASM ^†
Andorra	AND ^†
Angola	AGO
Anguilla	AIA ^†
Antarctica	ATA
Antigua and Barbuda	ATG ^†
Argentina	ARG
Armenia	ARM
Aruba	ABW ^†
Arunachal Pradesh	XAP
Australia	AUS
Austria	AUT
Azerbaijan	AZE
Azores Islands (grouped with Portugal)	PRT
Bahamas	BHS
Bahrain	BHR ^†
Bangladesh	BGD
Barbados	BRB ^†
Belarus	BLR
Belgium	BEL
Belize	BLZ
Benin	BEN
Bermuda	BMU ^†
Bhutan	BTN
Bir Tawil	XBT
Bolivia (Plurinational State of)	BOL
Bonaire	BES ^†
Bosnia and Herzegovina	BIH
Botswana	BWA
Bouvet Island	BVT ^†
Brazil	BRA
British Virgin Islands	VGB ^†
Brunei Darussalam	BRN
Bulgaria	BGR
Burkina Faso	BFA
Burundi	BDI
Cabo Verde	CPV
Cambodia	KHM
Cameroon	CMR
Canada	CAN
Canary Islands (grouped with Spain)	ESP
Cayman Islands	CYM ^†
Central African Republic	CAF
Chad	TCD
Chagos Archipelago (grouped with Mauritius)	MUS
Chile	CHL
China	CHN
Christmas Island	CXR ^†
Cocos (Keeling) Islands	CCK ^†
Colombia	COL
Comoros	COM
Congo	COG
Cook Islands	COK ^†
Costa Rica	CRI
Côte d'Ivoire	CIV
Croatia	HRV
Cuba	CUB
Curaçao	CUW ^†
Cyprus	CYP
Czechia	CZE
Democratic People's Republic of Korea	PRK
Democratic Republic of the Congo	COD
Denmark	DNK
Djibouti	DJI
Dominica	DMA
Dominican Republic	DOM
Ecuador	ECU
Egypt	EGY
El Salvador	SLV
Equatorial Guinea	GNQ
Eritrea	ERI
Estonia	EST
Eswatini	SWZ
Ethiopia	ETH
Falkland Islands (Malvinas)	FLK
Faroe Islands	FRO ^†
Fiji	FJI
Finland	FIN
France	FRA
French Guiana	GUF
French Polynesia	PYF
French Southern Territories	ATF
Gabon	GAB
Galápagos Islands (grouped with Ecuador)	ECU
Gambia	GMB
Gaza (grouped with State of Palestine)	PSE
Georgia	GEO
Germany	DEU
Ghana	GHA
Gibraltar	GIB ^†
Greece	GRC
Greenland	GRL
Grenada	GRD ^†
Guadeloupe	GLP
Guam	GUM
Guatemala	GTM
Guernsey	GGY ^†
Guinea	GIN
Guinea-Bissau	GNB
Guyana	GUY
Haiti	HTI
Halaib Triangle	XHT
Heard Island and McDonald Islands	HMD ^†
Honduras	HND
Hong Kong	HKG ^†
Hungary	HUN
Iceland	ISL
Ilemi Triangle	XIT
India	IND
Indonesia	IDN
Iran (Islamic Republic of)	IRN
Iraq	IRQ
Ireland	IRL
Isle of Man	IMN ^†
Israel	ISR
Italy	ITA
Jamaica	JAM
Jammu and Kashmir	XJK
Japan	JPN
Jersey	JEY ^†
Jordan	JOR
Kazakhstan	KAZ
Kenya	KEN
Kingdom of the Netherlands	NLD
Kiribati	KIR ^†
Kuwait	KWT
Kyrgyzstan	KGZ
Lao People's Democratic Republic	LAO
Latvia	LVA
Lebanon	LBN
Lesotho	LSO
Liberia	LBR
Libya	LBY
Liechtenstein	LIE ^†
Lithuania	LTU
Luxembourg	LUX
Macao	MAC ^†
Madagascar	MDG
Madeira Island (grouped with Portugal)	PRT
Malawi	MWI
Malaysia	MYS
Maldives	MDV ^†
Mali	MLI
Malta	MLT ^†
Marshall Islands	MHL ^†
Martinique	MTQ
Mauritania	MRT
Mauritius	MUS
Mayotte	MYT ^†
Mexico	MEX
Micronesia (Federated States of)	FSM ^†
Monaco	MCO ^†
Mongolia	MNG
Montenegro	MNE
Montserrat	MSR ^†
Morocco	MAR
Mozambique	MOZ
Myanmar	MMR
Namibia	NAM
Nauru	NRU ^†
Nepal	NPL
New Caledonia	NCL
New Zealand	NZL
Nicaragua	NIC
Niger	NER
Nigeria	NGA
Niue	NIU ^†
Norfolk Island	NFK ^†
North Macedonia	MKD
Northern Mariana Islands	MNP ^†
Norway	NOR
Oman	OMN
Pakistan	PAK
Palau	PLW ^†
Panama	PAN
Papua New Guinea	PNG
Paraguay	PRY
Peru	PER
Philippines	PHL
Pitcairn	PCN ^†
Poland	POL
Portugal	PRT
Puerto Rico	PRI
Qatar	QAT
Republic of Korea	KOR
Republic of Moldova	MDA
Réunion	REU
Romania	ROU
Russian Federation	RUS
Rwanda	RWA
Saba	BES ^†
Saint Barthélemy	BLM ^†
Saint Helena	SHN ^†
Saint Kitts and Nevis	KNA ^†
Saint Lucia	LCA ^†
Saint Martin	MAF ^†
Saint Pierre and Miquelon	SPM ^†
Saint Vincent and the Grenadines	VCT ^†
Samoa	WSM
Sao Tome and Principe	STP
Saudi Arabia	SAU
Senegal	SEN
Serbia	SRB
Seychelles	SYC ^†
Sierra Leone	SLE
Singapore	SGP ^†
Sint Eustatius	BES ^†
Sint Maarten	SXM ^†
Slovakia	SVK
Slovenia	SVN
Solomon Islands	SLB
Somalia	SOM
South Africa	ZAF
South Georgia and the South Sandwich Islands	SGS
South Sudan	SSD
Spain	ESP
Sri Lanka	LKA
Sudan	SDN
Suriname	SUR
Svalbard and Jan Mayen Islands	SJM
Sweden	SWE
Switzerland	CHE
Syrian Arab Republic	SYR
Taiwan	TWN
Tajikistan	TJK
Thailand	THA
Timor-Leste	TLS
Togo	TGO
Tokelau	TKL ^†
Tonga	TON ^†
Trinidad and Tobago	TTO
Tunisia	TUN
Türkiye	TUR
Turkmenistan	TKM
Turks and Caicos Islands	TCA ^†
Tuvalu	TUV ^†
Uganda	UGA
Ukraine	UKR
United Arab Emirates	ARE
United Kingdom of Great Britain and Northern Ireland	GBR
United Republic of Tanzania	TZA
United States of America	USA
United States Virgin Islands	VIR ^†
Uruguay	URY
Uzbekistan	UZB
Vanuatu	VUT
Venezuela (Bolivarian Republic of)	VEN
Viet Nam	VNM
West Bank (grouped with State of Palestine)	PSE
Western Sahara	ESH
Yemen	YEM
Zambia	ZMB
Zimbabwe	ZWE

View full list of ISO-3 codes

locationmode: 'USA-states'

Set locationmode: 'USA-states' to use two-letter US state abbreviations in locations.

var data = [{
    type: 'choropleth',
    locations: ['CA', 'TX', 'NY', 'FL', 'IL'],
    locationmode: 'USA-states',
    z: [95, 88, 92, 85, 78],
    colorscale: 'Reds'
}];

var layout = {
    title: 'USA States Choropleth',
    geo: {
        scope: 'usa'
    }
};

Plotly.newPlot('myDiv', data, layout);

Supported US State Codes

The following state codes are supported when locationmode='USA-states':

State	Code
Alabama	AL
Alaska	AK
Arizona	AZ
Arkansas	AR
California	CA
Colorado	CO
Connecticut	CT
Delaware	DE
District of Columbia	DC
Florida	FL
Georgia	GA
Hawaii	HI
Idaho	ID
Illinois	IL
Indiana	IN
Iowa	IA
Kansas	KS
Kentucky	KY
Louisiana	LA
Maine	ME
Maryland	MD
Massachusetts	MA
Michigan	MI
Minnesota	MN
Mississippi	MS
Missouri	MO
Montana	MT
Nebraska	NE
Nevada	NV
New Hampshire	NH
New Jersey	NJ
New Mexico	NM
New York	NY
North Carolina	NC
North Dakota	ND
Ohio	OH
Oklahoma	OK
Oregon	OR
Pennsylvania	PA
Rhode Island	RI
South Carolina	SC
South Dakota	SD
Tennessee	TN
Texas	TX
Utah	UT
Vermont	VT
Virginia	VA
Washington	WA
West Virginia	WV
Wisconsin	WI
Wyoming	WY

locationmode: 'country names'

Set locationmode: 'country names' to use full country names in locations.

Names are resolved by country-iso-search, which matches a country's name, its ISO-3166 and UN M49 codes, and a curated set of aliases — historical and native names, and common alternates. Matching ignores case, accents, and punctuation, so 'Cote d'Ivoire', 'Türkiye', and 'St. Kitts and Nevis' all resolve. See the library's country list for every accepted name and alias. A name that doesn't resolve is logged to the console and that location is skipped.

var data = [{
    type: 'choropleth',
    locations: ['United States', 'Canada', 'United Kingdom'],
    locationmode: 'country names',
    z: [1, 1, 1],
    colorscale: [[0, '#636efa'], [1, '#636efa']],
    showscale: false
}];

var layout = {
    title: 'Choropleth with Country Names'
};

Plotly.newPlot('myDiv', data, layout);