README.md

Countries GraphQL API

A public GraphQL API for information about countries, continents, and languages. This project uses Countries List and 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.
2. The Country.continent and Country.languages are now objects and arrays of objects, respectively.
3. 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.
4. Each Country has an array of states populated by their states/provinces, if any.
5. Each Country also has an awsRegion field that shows its nearest AWS region, powered by country-to-aws-region.

Writing queries

query GetCountry {
  country(code: "BR") {
    name
    native
    capital
    emoji
    currency
    languages {
      code
      name
    }
  }
}

The above GraphQL query will produce the following JSON response:

{
  "data": {
    "country": {
      "name": "Brazil",
      "native": "Brasil",
      "capital": "Brasília",
      "emoji": "🇧🇷",
      "currency": "BRL",
      "languages": [
        {
          "code": "pt",
          "name": "Portuguese"
        }
      ]
    }
  }
}

Check out the playground 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 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.

Here are some examples of filtering that you can copy and paste into the playground to try for yourself:

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
• React Native
• ReasonML
• Country quiz app (React, TypeScript)
• Python
• Seed
• Country Searcher

License

MIT