Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/trevorblades/countries
🌎 Public GraphQL API for information about countries
https://github.com/trevorblades/countries
api apollo continents countries free graphql graphql-api languages provinces public public-api schema states
Last synced: 30 days ago
JSON representation
🌎 Public GraphQL API for information about countries
- Host: GitHub
- URL: https://github.com/trevorblades/countries
- Owner: trevorblades
- License: mit
- Created: 2018-10-11T04:08:50.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2024-01-03T21:29:49.000Z (10 months ago)
- Last Synced: 2024-09-28T21:23:19.601Z (about 1 month ago)
- Topics: api, apollo, continents, countries, free, graphql, graphql-api, languages, provinces, public, public-api, schema, states
- Language: TypeScript
- Homepage: https://countries.trevorblades.com
- Size: 1.88 MB
- Stars: 466
- Watchers: 10
- Forks: 70
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
Countries GraphQL API
[](https://github.com/trevorblades/countries/actions)
[](CODE_OF_CONDUCT.md)
[](https://twitter.com/trevorblades)
A public GraphQL API for information about countries, continents, and languages. This project uses [Countries List](https://annexare.github.io/Countries/) and [`provinces`](https://www.npmjs.com/package/provinces) as data sources, so the schema follows the shape of that data, with a few exceptions:
1. The codes used to key the objects in the original data are available as a `code` property on each item returned from the API.
1. The `Country.continent` and `Country.languages` are now objects and arrays of objects, respectively.
1. The `Country.currency` and `Country.phone` fields _sometimes_ return a comma-separated list of values. For this reason, this API also exposes `currencies` and `phones` fields that are arrays of all currencies and phone codes for a country.
1. Each `Country` has an array of `states` populated by their states/provinces, if any.
1. Each `Country` also has an `awsRegion` field that shows its nearest AWS region, powered by [`country-to-aws-region`](https://github.com/Zeryther/country-to-aws-region).
## Writing queries
```graphql
query GetCountry {
country(code: "BR") {
name
native
capital
emoji
currency
languages {
code
name
}
}
}
```
The above GraphQL query will produce the following JSON response:
```json
{
"data": {
"country": {
"name": "Brazil",
"native": "Brasil",
"capital": "Brasília",
"emoji": "🇧🇷",
"currency": "BRL",
"languages": [
{
"code": "pt",
"name": "Portuguese"
}
]
}
}
}
```
Check out [the playground](https://countries.trevorblades.com) to explore the schema and test out some queries.
## Filtering
The `countries`, `continents`, and `languages` top-level `Query` fields accept an optional `filter` argument that causes results to be filtered on one or more subfields. The `continents` and `languages` fields can be filtered by their `code`, while `countries` can be filtered by `code`, `currency`, or `continent`.
> Note: The `continent` filter on the `Query.countries` field must be the continent code, i.e. "SA" for South America.
The filtering logic is powered by [sift](https://github.com/crcn/sift.js) and this API supports the following operators: `eq`, `ne`, `in`, `nin`, and `regex`. To learn more about these operators and how they work, check out [the sift docs](https://github.com/crcn/sift.js#supported-operators).
Here are some examples of filtering that you can copy and paste into [the playground](https://countries.trevorblades.com) to try for yourself:
```graphql
query ListCountriesThatUseUSD {
countries(filter: { currency: { eq: "USD" } }) {
code
name
}
}
query ListCountriesInNAFTA {
countries(filter: { code: { in: ["US", "CA", "MX"] } }) {
code
name
languages {
name
}
}
}
query ListCountriesThatBeginWithTheLetterA {
countries(filter: { name: { regex: "^A" } }) {
code
name
currency
}
}
```
## Examples
- [React](./examples/react)
- [React Native](https://github.com/muhzi4u/country-directory-app)
- [ReasonML](https://medium.com/@idkjs/reasonml-and-graphql-without-graphql-part-1-192c2e9e349c)
- [Country quiz app](https://github.com/byrichardpowell/Country-Quiz) (React, TypeScript)
- [Python](./examples/python)
- [Seed](https://github.com/seed-rs/seed/tree/master/examples/graphql)
- [Country Searcher](https://github.com/FranP-code/country-searcher)
## License
[MIT](./LICENSE)
[](https://stellate.co/?ref=powered-by)