README.md 8.47 KB
Newer Older
Alejandro Matos's avatar
Alejandro Matos committed
1
# About this Project
Alejandro Matos's avatar
Alejandro Matos committed
2
This project is inspired on restcountries.eu by Fayder Florez. As it hasn't had any activity in at least 14 months, I decided to take action :)
Alejandro Matos's avatar
Alejandro Matos committed
3
4

# REST Countries
Alejandro Matos's avatar
Alejandro Matos committed
5
You can access API through https://restcountries.com/v3/all
6
7
8
9
10

# TODO:
* [x] Add SSL
* [ ] Solve many issues reported in the GitHub page for original countries
* [ ] Add Chinese, Taiwanese and Hongkonian
Alejandro Matos's avatar
Alejandro Matos committed
11

Alejandro Matos's avatar
Alejandro Matos committed
12
# Contributing
13
14
15
Any help is welcome! Just edit the file `countriesV2.json`. If you want to edit V3, please refer to 
[this](https://github.com/mledoze/countries/blob/master/countries.json) file or create an issue in the
[original project](https://github.com/mledoze/countries).
Alejandro Matos's avatar
Alejandro Matos committed
16

Alejandro Matos's avatar
Alejandro Matos committed
17
18
19
# Donations
If you feel like helping me, you're welcome to [donate](https://www.paypal.me/amatosg/15) or you can also [buy me a coffee](https://www.buymeacoffee.com/amatos) :)

Alejandro Matos's avatar
Alejandro Matos committed
20
21
# API Endpoints

22
23
24
25
Currently there are 2 versions:
- Version 2 is the original version from restcountries.eu by Fayder Florez
- Version 3 is the implementation from [this project](https://github.com/mledoze/countries)

Alejandro Matos's avatar
Alejandro Matos committed
26
27
28
29
Below are described the REST endpoints available that you can use to search for countries

## All

30
### V2
Alejandro Matos's avatar
Alejandro Matos committed
31
``` html
32
https://restcountries.com/v2/all
Alejandro Matos's avatar
Alejandro Matos committed
33
34
```

35
36
37
38
39
40
### V3
``` html
https://restcountries.com/v3/all
```


Alejandro Matos's avatar
Alejandro Matos committed
41
42
## Name

43
### V2
Alejandro Matos's avatar
Alejandro Matos committed
44
45
46
Search by country name. It can be the native name or partial name

``` javascript
47
https://restcountries.com/v2/name/{name}
Alejandro Matos's avatar
Alejandro Matos committed
48
49
50
```

``` html
51
https://restcountries.com/v2/name/eesti
Alejandro Matos's avatar
Alejandro Matos committed
52
53
54
```

``` html
55
https://restcountries.com/v2/name/united
Alejandro Matos's avatar
Alejandro Matos committed
56
57
```

58
59
60
61
62
### V3
Search by country name. It can be the common or official value
``` html
https://restcountries.com/v3/name/{name}
```
Alejandro Matos's avatar
Alejandro Matos committed
63

64
65
66
``` html
https://restcountries.com/v3/name/eesti
```
Alejandro Matos's avatar
Alejandro Matos committed
67

68
69
70
71
72
73
74
75
76
``` html
https://restcountries.com/v3/name/deutschland
```

## Full Name
### V2
Search by country's full name

``` html
77
https://restcountries.com/v2/name/{name}?fullText=true
Alejandro Matos's avatar
Alejandro Matos committed
78
79
80
```

``` html
81
https://restcountries.com/v2/name/aruba?fullText=true
Alejandro Matos's avatar
Alejandro Matos committed
82
83
```

84
85
86
87
88
### V3
Search by country's full name. It can be the common or official value
``` html
https://restcountries.com/v3/name/{name}?fullText=true
```
Alejandro Matos's avatar
Alejandro Matos committed
89

90
91
92
93
94
``` html
https://restcountries.com/v3/name/aruba?fullText=true
```
## Code
### V2
Alejandro Matos's avatar
Alejandro Matos committed
95
96
Search by ISO 3166-1 2-letter or 3-letter country code

97
``` html
98
https://restcountries.com/v2/alpha/{code}
Alejandro Matos's avatar
Alejandro Matos committed
99
100
101
```

``` html
102
https://restcountries.com/v2/alpha/co
Alejandro Matos's avatar
Alejandro Matos committed
103
104
105
```

``` html
106
https://restcountries.com/v2/alpha/col
Alejandro Matos's avatar
Alejandro Matos committed
107
```
108
109
### V3
Search by cca2, ccn3, cca3 or cioc country code (yes, any!)
Alejandro Matos's avatar
Alejandro Matos committed
110

111
112
113
114
115
116
117
118
119
120
121
``` html
https://restcountries.com/v3/alpha/{code}
```

``` html
https://restcountries.com/v3/alpha/co
```

``` html
https://restcountries.com/v3/alpha/col
```
Alejandro Matos's avatar
Alejandro Matos committed
122

123
124
125
126
127
``` html
https://restcountries.com/v3/alpha/170
```
## List of codes
### V2
Alejandro Matos's avatar
Alejandro Matos committed
128
129
Search by list of ISO 3166-1 2-letter or 3-letter country codes

130
``` html
131
https://restcountries.com/v2/alpha?codes={code},{code},{code}
Alejandro Matos's avatar
Alejandro Matos committed
132
133
134
```

``` html
135
136
137
138
139
140
https://restcountries.com/v2/alpha?codes=col,no,ee,pe
```
### V3
Search by cca2, ccn3, cca3 or cioc country code (yes, any!)
``` html
https://restcountries.com/v3/alpha?codes={code},{code},{code}
Alejandro Matos's avatar
Alejandro Matos committed
141
142
```

143
144
145
``` html
https://restcountries.com/v3/alpha?codes=170,no,est,pe
```
Alejandro Matos's avatar
Alejandro Matos committed
146
## Currency
147
### V2
Alejandro Matos's avatar
Alejandro Matos committed
148
149
Search by ISO 4217 currency code

150
``` html
151
https://restcountries.com/v2/currency/{currency}
Alejandro Matos's avatar
Alejandro Matos committed
152
153
```
``` html
154
https://restcountries.com/v2/currency/cop
Alejandro Matos's avatar
Alejandro Matos committed
155
```
156
157
158
159
160
161
162
163
### V3
Search by currency code or name
``` html
https://restcountries.com/v3/currency/{currency}
```
``` html
https://restcountries.com/v3/currency/cop
```
Alejandro Matos's avatar
Alejandro Matos committed
164

165
166
167
168
169
170
171
172
173
### Demonym
### V3
Now you can search by how a citizen is called.
``` html
https://restcountries.com/v3/demonym/{demonym}
```
``` html
https://restcountries.com/v3/demonym/peruvian
```
Alejandro Matos's avatar
Alejandro Matos committed
174

175
176
## Language
### V2
Alejandro Matos's avatar
Alejandro Matos committed
177
178
179
Search by ISO 639-1 language code

``` javascript
180
https://restcountries.com/v2/lang/{et}
Alejandro Matos's avatar
Alejandro Matos committed
181
182
```
``` html
183
https://restcountries.com/v2/lang/es
Alejandro Matos's avatar
Alejandro Matos committed
184
185
```

186
187
188
189
190
191
192
193
194
195
196
197
### V3
Search by language code or name
``` html
https://restcountries.com/v3/lang/{currency}
```
``` html
https://restcountries.com/v3/lang/cop
```
``` html
https://restcountries.com/v3/lang/spanish
```

Alejandro Matos's avatar
Alejandro Matos committed
198
199
## Capital city

200
201
_This is the same in both versions_

Alejandro Matos's avatar
Alejandro Matos committed
202
203
204
Search by capital city

``` javascript
205
https://restcountries.com/v2/capital/{capital}
Alejandro Matos's avatar
Alejandro Matos committed
206
207
```
``` html
208
https://restcountries.com/v2/capital/tallinn
Alejandro Matos's avatar
Alejandro Matos committed
209
210
```

211
212
213
214
215
216
``` javascript
https://restcountries.com/v3/capital/{capital}
```
``` html
https://restcountries.com/v3/capital/tallinn
```
Alejandro Matos's avatar
Alejandro Matos committed
217

218
219
## Calling code
### V2
Alejandro Matos's avatar
Alejandro Matos committed
220
221
Search by calling code

222
``` html
223
https://restcountries.com/v2/callingcode/{callingcode}
Alejandro Matos's avatar
Alejandro Matos committed
224
225
```
``` html
226
https://restcountries.com/v2/callingcode/372
Alejandro Matos's avatar
Alejandro Matos committed
227
```
228
229
230
### V3
In version 3, calling codes are in the _idd_ object. There is no implementation 
to search by calling codes in V3.
Alejandro Matos's avatar
Alejandro Matos committed
231

232
233
234
## Region
### V2
In version 2 regions are _continent_ and subregions are _region_
235
Search by continent: Africa, Americas, Asia, Europe, Oceania
Alejandro Matos's avatar
Alejandro Matos committed
236

237
238
``` html
https://restcountries.com/v2/continent/{continent}
Alejandro Matos's avatar
Alejandro Matos committed
239
240
```
``` html
241
https://restcountries.com/v2/continent/europe
Alejandro Matos's avatar
Alejandro Matos committed
242
```
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
### V3
In version 3, continents are _Regions_ and regions are _Subregions_

``` html
https://restcountries.com/v2/region/{region}
```
``` html
https://restcountries.com/v2/region/europe
```
## Subregions
###V3
You can search by subregions
``` html
https://restcountries.com/v2/subregion/{subregion}
```
``` html
https://restcountries.com/v2/subregion/Northern Europe
```

## Regional Bloc (*Version 2 only*)

Alejandro Matos's avatar
Alejandro Matos committed
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281


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)

282
``` html
283
https://restcountries.com/v2/regionalbloc/{regionalbloc}
Alejandro Matos's avatar
Alejandro Matos committed
284
285
```
``` html
286
https://restcountries.com/v2/regionalbloc/eu
Alejandro Matos's avatar
Alejandro Matos committed
287
288
```

289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
## Translation
You can search by any translation name
``` html
https://restcountries.com/v3/translation/{translation}
```
``` html
https://restcountries.com/v3/translation/germany
```
``` html
https://restcountries.com/v3/translation/alemania
```
``` html
https://restcountries.com/v3/translation/Saksamaa
```

Alejandro Matos's avatar
Alejandro Matos committed
304
305
306
## Response Example

``` html
307
https://restcountries.com/v2/alpha/col
Alejandro Matos's avatar
Alejandro Matos committed
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
```

``` json
[[{
	"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"
	},
350
	"flag": "https://restcountries.com/data/col.svg",
Alejandro Matos's avatar
Alejandro Matos committed
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
	"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.

``` javascript
370
https://restcountries.com/v2/{service}?fields={field},{field},{field}
Alejandro Matos's avatar
Alejandro Matos committed
371
372
```
``` html
373
https://restcountries.com/v2/all?fields=name,capital,currencies
Alejandro Matos's avatar
Alejandro Matos committed
374
```
Lost Coder's avatar
Lost Coder committed
375
376
377
## Using this Project

- [Nations24](https://nations24.com)
Alejandro Matos's avatar
Alejandro Matos committed
378
379

## Similar projects
380
* [REST Countries] (original project)
Alejandro Matos's avatar
Alejandro Matos committed
381
382
383
384
385
386
387
388
389
390
391
392
393
* [Countries of the world]
* [REST Countries Node.js]
* [REST Countries Ruby]
* [REST Countries Go]
* [REST Countries Python]
* [world-currencies]

[world-currencies]: https://github.com/wiredmax/world-currencies
[REST Countries Node.js]: https://github.com/aredo/restcountries
[REST Countries Ruby]: https://github.com/davidesantangelo/restcountry
[REST Countries Go]: https://github.com/alediaferia/gocountries
[REST Countries Python]: https://github.com/SteinRobert/python-restcountries
[Countries of the world]: http://countries.petethompson.net
394
[REST Countries]: https://github.com/apilayer/restcountries