5 ms·

Get information about any country via a RESTful API

44 points by vaeke 13y ago

NKCSS 13y ago
That's pretty awesome :) Simple and too the point. Nice project :)
jodyr 13y ago
Some of the data seems to be incorrect: http://restcountries.eu/rest/alpha2/za http://restcountries.eu/rest/alpha2/za The South African currency is ZAR, not SOS. Cape Town is the legislative capital, but not _the_ capital. If you search by currency for ZAR: http://restcountries.eu/rest/currency/zar http://restcountries.eu/rest/currency/zar You get South Georgia. I assume that's meant to be South Africa.
- Svip 13y ago
  And what about the Netherlands which has two capitals? A national capital (Amsterdam) and an administrative capital (Den Haag)? And what about countries that use two currencies... oh wait, Cuba actually lists two currencies; never mind.
  - tokenizerrr 13y ago
    As a Dutch person I would say Amsterdam would be the correct listing as it is the official capital, which is what is listed.
- godfried 13y ago
  SOS is the Somali shilling. It seems currencies for Slovakia (No idea what currency XSU is) to South Georgia have shifted one country down.
- apierre 13y ago
  Same for "calling code". 44 returns Guernsey which is correct but I would expect the UK instead.
agilebyte 13y ago
You have "CZ,Ceska" as an alternative spelling, but in fact it is "Česká republika" or "Česko". Especially since you have "AT,Österreich" for Austria. Shall I submit it to mledoze/countries instead? Edit: solved - submitted a pull request
contrahax 13y ago
Why not just publish a JSON file? It's not like the data source is that large or changes often. No reason to have an API for this
- icebraining 13y ago
  Apparently the data does come from a JSON file: https://github.com/mledoze/countries/blob/master/countries.json https://github.com/mledoze/countries/blob/master/countries.j...
icebraining 13y ago
"JSON Data is taken from https://github.com/mledoze/countries" https://github.com/mledoze/countries" The data is cool, but seems overkill to do an HTTP call when the full dataset is 11K (gzipped).
racbart 13y ago
This is nice if considered a programming exercise but it's actually pretty useless for real world use. This data is static, that is it very rarely changes. The whole dataset is also very tiny. It's just better to store this data in-house and don't provide unnecessary point of potential failure by using an external service. An idea on how to make it more useful is to provide downloadable data dump in several formats suited for immediate import into various data stores. An extra addition might be modules for popular frameworks providing access to this (local) data in all the ways your web service does. I'm not trying to diss, just trying to find some value for real world usage. The service is neat otherwise.
- icebraining 13y ago
  The project where the data comes from actually offers dumps in three different formats: https://github.com/mledoze/countries https://github.com/mledoze/countries
- darrhiggs 13y ago
  >> It's just better to store this data in-house and don't provide unnecessary point of potential failure by using an external service. Isn't this the point of rfc2616 sec13? I haven't looked, but if there are etags etc then I think a computer is better than a human at looking for new data, no?
- vaeke 13y ago
  totally get your point. although there are cases when using an external service is actually more convenient. maybe riskier but still convenient. thanks.
chatman 13y ago
Pretty crappy search, query for "india" returns "British Indian Ocean Territory" as the first result.
- vaeke 13y ago
  ordering by "relevance" is coming =)
masklinn 13y ago
Obligatory warning: API is absolutely not restful.
- ddoolin 13y ago
  But it even has "rest" in the URL! You mean that doesn't make it RESTful (rest-full?)
- cognivore 13y ago
  Since the project seems to have an educational bent, what would the proper REST interface for it look like? GET: http://restcountries.eu/rest/alpha/ee http://restcountries.eu/rest/alpha/ee would be http://restcountries.eu/countries?alpha=ee http://restcountries.eu/countries?alpha=ee http://restcountries.eu/rest/name/norge http://restcountries.eu/rest/name/norge would be http://restcountries.eu/countries?name=norge http://restcountries.eu/countries?name=norge That seems right, right?
  - smizell 13y ago
    Neither is more or less RESTful than the other. The media type and link relations express to the client what resource is being returned, not the URL itself.
- smizell 13y ago
  Just wanted to add some thoughts on how one could try to make this RESTful. First, if it were me, I'd pick a media type that can express hyperlinks in JSON (since JSON knows nothing about hyperlinks), maybe something like HAL [1]. Next, I would define my link relations for this API, which in this case would be a collection of countries and the countries themselves (so at least two different types of resources). After creating the representations of each of these resources, I would then create URI templates in my root response (I guess found at /rest) that allow for the searching aspect that this site is providing, which would be something like: { "_links": { "search_by_name": { "href": "/rest/name/{name}", "templated": true } } } I may build on to this to provide other resources, like a collection of capitals, each with a link to "/rest/capital/{capital_city}", or a resource of currencies, linking to "/rest/currency/{currency}". The goal of all of this would be to tell the client how to find resources rather than having that hard-coded into the client. These are just some first steps toward being RESTful, and there are lots of different directions you could take this and still be RESTful. edit: example was incomplete [1] http://stateless.co/hal_specification.html http://stateless.co/hal_specification.html
echeese 13y ago
The capital of Canada is Ottawa, not Ottowa.
chrishas35 13y ago
The callingcode endpoint only returns one result even when there is more than one that qualifies, as is the case with 1 and USA and Canada (and others that are part of the North American Numbering Plan)
ismaelc 13y ago
(Disclaimer: I work for Mashape). I added this API to Mashape https://www.mashape.com/community/rest-countries-1#!documentation https://www.mashape.com/community/rest-countries-1#!document...
gulbrandr 13y ago
Maintainer of the dataset here. Most of the inacurracies have been fixed now. More data will come soon. Thank you for all the feedback, I appreciate it!

44 points by vaeke 13y ago

NKCSS 13y ago

That's pretty awesome :) Simple and too the point. Nice project :)

jodyr 13y ago

Some of the data seems to be incorrect: http://restcountries.eu/rest/alpha2/za http://restcountries.eu/rest/alpha2/za The South African currency is ZAR, not SOS. Cape Town is the legislative capital, but not _the_ capital. If you search by currency for ZAR: http://restcountries.eu/rest/currency/zar http://restcountries.eu/rest/currency/zar You get South Georgia. I assume that's meant to be South Africa.

Svip 13y ago
And what about the Netherlands which has two capitals? A national capital (Amsterdam) and an administrative capital (Den Haag)? And what about countries that use two currencies... oh wait, Cuba actually lists two currencies; never mind.
- tokenizerrr 13y ago
  As a Dutch person I would say Amsterdam would be the correct listing as it is the official capital, which is what is listed.
godfried 13y ago
SOS is the Somali shilling. It seems currencies for Slovakia (No idea what currency XSU is) to South Georgia have shifted one country down.
apierre 13y ago
Same for "calling code". 44 returns Guernsey which is correct but I would expect the UK instead.

agilebyte 13y ago

You have "CZ,Ceska" as an alternative spelling, but in fact it is "Česká republika" or "Česko". Especially since you have "AT,Österreich" for Austria. Shall I submit it to mledoze/countries instead? Edit: solved - submitted a pull request

contrahax 13y ago

Why not just publish a JSON file? It's not like the data source is that large or changes often. No reason to have an API for this

icebraining 13y ago
Apparently the data does come from a JSON file: https://github.com/mledoze/countries/blob/master/countries.json https://github.com/mledoze/countries/blob/master/countries.j...

icebraining 13y ago

"JSON Data is taken from https://github.com/mledoze/countries" https://github.com/mledoze/countries" The data is cool, but seems overkill to do an HTTP call when the full dataset is 11K (gzipped).

racbart 13y ago

This is nice if considered a programming exercise but it's actually pretty useless for real world use. This data is static, that is it very rarely changes. The whole dataset is also very tiny. It's just better to store this data in-house and don't provide unnecessary point of potential failure by using an external service. An idea on how to make it more useful is to provide downloadable data dump in several formats suited for immediate import into various data stores. An extra addition might be modules for popular frameworks providing access to this (local) data in all the ways your web service does. I'm not trying to diss, just trying to find some value for real world usage. The service is neat otherwise.

icebraining 13y ago
The project where the data comes from actually offers dumps in three different formats: https://github.com/mledoze/countries https://github.com/mledoze/countries
darrhiggs 13y ago
>> It's just better to store this data in-house and don't provide unnecessary point of potential failure by using an external service. Isn't this the point of rfc2616 sec13? I haven't looked, but if there are etags etc then I think a computer is better than a human at looking for new data, no?
vaeke 13y ago
totally get your point. although there are cases when using an external service is actually more convenient. maybe riskier but still convenient. thanks.

chatman 13y ago

Pretty crappy search, query for "india" returns "British Indian Ocean Territory" as the first result.

vaeke 13y ago
ordering by "relevance" is coming =)

masklinn 13y ago

Obligatory warning: API is absolutely not restful.

ddoolin 13y ago
But it even has "rest" in the URL! You mean that doesn't make it RESTful (rest-full?)
cognivore 13y ago
Since the project seems to have an educational bent, what would the proper REST interface for it look like? GET: http://restcountries.eu/rest/alpha/ee http://restcountries.eu/rest/alpha/ee would be http://restcountries.eu/countries?alpha=ee http://restcountries.eu/countries?alpha=ee http://restcountries.eu/rest/name/norge http://restcountries.eu/rest/name/norge would be http://restcountries.eu/countries?name=norge http://restcountries.eu/countries?name=norge That seems right, right?
- smizell 13y ago
  Neither is more or less RESTful than the other. The media type and link relations express to the client what resource is being returned, not the URL itself.
smizell 13y ago
Just wanted to add some thoughts on how one could try to make this RESTful. First, if it were me, I'd pick a media type that can express hyperlinks in JSON (since JSON knows nothing about hyperlinks), maybe something like HAL [1]. Next, I would define my link relations for this API, which in this case would be a collection of countries and the countries themselves (so at least two different types of resources). After creating the representations of each of these resources, I would then create URI templates in my root response (I guess found at /rest) that allow for the searching aspect that this site is providing, which would be something like: { "_links": { "search_by_name": { "href": "/rest/name/{name}", "templated": true } } } I may build on to this to provide other resources, like a collection of capitals, each with a link to "/rest/capital/{capital_city}", or a resource of currencies, linking to "/rest/currency/{currency}". The goal of all of this would be to tell the client how to find resources rather than having that hard-coded into the client. These are just some first steps toward being RESTful, and there are lots of different directions you could take this and still be RESTful. edit: example was incomplete [1] http://stateless.co/hal_specification.html http://stateless.co/hal_specification.html

echeese 13y ago

The capital of Canada is Ottawa, not Ottowa.

chrishas35 13y ago

The callingcode endpoint only returns one result even when there is more than one that qualifies, as is the case with 1 and USA and Canada (and others that are part of the North American Numbering Plan)

ismaelc 13y ago

(Disclaimer: I work for Mashape). I added this API to Mashape https://www.mashape.com/community/rest-countries-1#!documentation https://www.mashape.com/community/rest-countries-1#!document...

gulbrandr 13y ago

Maintainer of the dataset here. Most of the inacurracies have been fixed now. More data will come soon. Thank you for all the feedback, I appreciate it!