REST Countries

Forked from https://restcountries.eu

Differences from original

Packaged as a standalone micronaut service application
Removed /v1 API
Removed /contribute API
Added unicodeFlag attribute

Default port 5055

How to Deploy

Download JDK https://www.oracle.com/java/technologies/javase-downloads.html
Download and set paths for Maven https://maven.apache.org/download.cgi https://maven.apache.org/install.html
Run following to generate target jar files for Docker Container ./mvnw clean install
Build and start the container by running following docker-compose up --build
Access at http://localhost:5050

API Endpoints

Below are described the REST endpoints available that you can use to search for countries

Health Check

/health

All

/v2/all

Name

Search by country name. It can be the native name or partial name

/v2/name/{name}

/v2/name/eesti

/v2/name/united

Full Name

Search by country full name

/v2/name/{name}?fullText=true

/v2/name/aruba?fullText=true

Code

Search by ISO 3166-1 2-letter or 3-letter country code

/v2/alpha/{code}

/v2/alpha/co

/v2/alpha/col

List of codes

Search by list of ISO 3166-1 2-letter or 3-letter country codes

/v2/alpha?codes={code};{code};{code}

/v2/alpha?codes=col;no;ee

Currency

Search by ISO 4217 currency code

/v2/currency/{currency}

/v2/currency/cop

Language

Search by ISO 639-1 language code

/v2/lang/{et}

/v2/lang/es

Capital city

Search by capital city

/v2/capital/{capital}

/v2/capital/tallinn

Calling code

Search by calling code

/v2/callingcode/{callingcode}

/v2/callingcode/372

Region

Search by region: Africa, Americas, Asia, Europe, Oceania

/v2/region/{region}

/v2/region/europe

Regional Bloc

Search by regional bloc:

EU (European Union)
EFTA (European Free Trade Association)
CARICOM (Caribbean Community)
PA (Pacific Alliance)
AU (African Union)
USAN (Union of South American Nations)
EEU (Eurasian Economic Union)
AL (Arab League)
ASEAN (Association of Southeast Asian Nations)
CAIS (Central American Integration System)
CEFTA (Central European Free Trade Agreement)
NAFTA (North American Free Trade Agreement)
SAARC (South Asian Association for Regional Cooperation)

/v2/regionalbloc/{regionalbloc}

/v2/regionalbloc/eu

Response Example

/v2/alpha/col

[[{
	"name": "Colombia",
	"topLevelDomain": [".co"],
	"alpha2Code": "CO",
	"alpha3Code": "COL",
	"callingCodes": ["57"],
	"capital": "Bogotá",
	"altSpellings": ["CO", "Republic of Colombia", "República de Colombia"],
	"region": "Americas",
	"subregion": "South America",
	"population": 48759958,
	"latlng": [4.0, -72.0],
	"demonym": "Colombian",
	"area": 1141748.0,
	"gini": 55.9,
	"timezones": ["UTC-05:00"],
	"borders": ["BRA", "ECU", "PAN", "PER", "VEN"],
	"nativeName": "Colombia",
	"numericCode": "170",
	"currencies": [{
		"code": "COP",
		"name": "Colombian peso",
		"symbol": "$"
	}],
	"languages": [{
		"iso639_1": "es",
		"iso639_2": "spa",
		"name": "Spanish",
		"nativeName": "Español"
	}],
	"translations": {
		"de": "Kolumbien",
		"es": "Colombia",
		"fr": "Colombie",
		"ja": "コロンビア",
		"it": "Colombia",
		"br": "Colômbia",
		"pt": "Colômbia"
	},
	"flag": "/data/col.svg",
    "unicodeFlag": "🇨🇴",
	"regionalBlocs": [{
		"acronym": "PA",
		"name": "Pacific Alliance",
		"otherAcronyms": [],
		"otherNames": ["Alianza del Pacífico"]
	}, {
		"acronym": "USAN",
		"name": "Union of South American Nations",
		"otherAcronyms": ["UNASUR", "UNASUL", "UZAN"],
		"otherNames": ["Unión de Naciones Suramericanas", "União de Nações Sul-Americanas", "Unie van Zuid-Amerikaanse Naties", "South American Union"]
	}]
}]

Filter Response

You can filter the output of your request to include only the specified fields.

/v2/{service}?fields={field};{field};{field}

/v2/all?fields=name;capital;currencies

Update Tool

Use scripts in dataupdate directory download updated country data from [https://github.com/mledoze/countries] and language code mapping data from [https://datahub.io/core/language-codes]. Requires Node.js and cUrl.

Currently it updates only country name translations.

cd dataupdate
./update.sh

Review the changes in src/main/java/resources/countriesV2.json and commit changes.

Sources

Similar projects

License

Mozilla Public License MPL 2.0

fais3000 / restcountries Goto Github PK

restcountries's Introduction