A free GraphQL API for comprehensive geographic data — countries, states, and cities worldwide. Perfect for applications needing location data, dropdown menus, maps, and geographic information systems.
🎯 Free & Open Source — No API keys required, no rate limits. This GraphQL API provides detailed geographic data including country ISO codes, phone codes, capitals, currencies, emojis, state coordinates, and city locations. Data sourced from thecountries-states-cities-database by Darshan Gada, with additional personally gathered data.
https://graphql.countriesql.com/graphql🚀 Playground:https://graphql.countriesql.comCountriesGet all countries with detailed information including ISO codes, phone codes, capital, currency, emoji, and coordinates.
{
"data": {
"Countries": [
{
"id": 1,
"iso2": "US",
"iso3": "USA",
"name": "United States",
"emoji": "🇺🇸",
"numeric_code": "840",
"phone_code": "+1",
"capital": "Washington D.C.",
"currency": "USD",
"currency_name": "US Dollar",
"currency_symbol": "$",
"tld": ".us",
"native": "United States",
"region": "Americas",
"subregion": "North America",
"longitude": -95.712891,
"latitude": 37.09024
}
]
}
}Country(iso2: String)Get detailed information about a specific country by ISO2 code.
| Argument | Type | Required | Description |
|---|---|---|---|
iso2 | String | ✓ Yes | Two-letter country code (e.g., "NG", "US", "GH") |
{
"data": {
"Country": {
"id": 162,
"iso2": "NG",
"iso3": "NGA",
"name": "Nigeria",
"emoji": "🇳🇬",
"numeric_code": "566",
"phone_code": "234",
"capital": "Abuja",
"currency": "NGN",
"currency_name": "Nigerian naira",
"currency_symbol": "₦",
"tld": ".ng",
"native": "Nigeria",
"region": "Africa",
"subregion": "Western Africa",
"longitude": 8,
"latitude": 10
}
}
}CountriesByRegion(region: String)Get all countries belonging to a specific region (e.g., Africa, Americas, Asia, Europe, Oceania).
| Argument | Type | Required | Description |
|---|---|---|---|
region | String | ✓ Yes | Region name (Africa, Americas, Asia, Europe, Oceania) |
{
"data": {
"CountriesByRegion": [
{
"id": 162,
"iso2": "NG",
"name": "Nigeria",
"emoji": "🇳🇬",
"phone_code": "234",
"capital": "Abuja",
"currency": "NGN",
"region": "Africa"
}
]
}
}CountriesBySubregion(subregion: String)Get all countries belonging to a specific subregion (e.g., Western Africa, Southeast Asia, South America).
| Argument | Type | Required | Description |
|---|---|---|---|
subregion | String | ✓ Yes | Subregion name (e.g., "Western Africa", "South America") |
{
"data": {
"CountriesBySubregion": [
{
"id": 162,
"iso2": "NG",
"name": "Nigeria",
"emoji": "🇳🇬",
"capital": "Abuja",
"region": "Africa",
"subregion": "Western Africa"
}
]
}
}StatesGet all states with their names and coordinates.
{
"data": {
"States": [
{
"id": 1,
"name": "Lagos",
"latitude": 6.5243793,
"longitude": 3.3792057,
"country_name": "Nigeria"
}
]
}
}StatesByCountry(country_name: String)Get all states for a specific country by country name.
| Argument | Type | Required | Description |
|---|---|---|---|
country_name | String | ✓ Yes | Full country name (e.g., "Nigeria", "Canada") |
{
"data": {
"StatesByCountry": [
{
"id": 53,
"name": "Ahafo",
"latitude": 7.5821372,
"longitude": -2.5497463
},
{
"id": 48,
"name": "Ashanti",
"latitude": 6.7470436,
"longitude": -1.5208624
}
]
}
}State(name: String)Get detailed information about a specific state by name.
| Argument | Type | Required | Description |
|---|---|---|---|
name | String | ✓ Yes | Name of the state (e.g., "California", "Lagos") |
{
"data": {
"State": {
"id": 48,
"name": "Ashanti",
"latitude": 6.7470436,
"longitude": -1.5208624,
"country_name": "Ghana"
}
}
}CitiesByCountry(country_name: String)Get all cities for a specific country. Returns city names with coordinates.
| Argument | Type | Required | Description |
|---|---|---|---|
country_name | String | ✓ Yes | Full country name (e.g., "Nigeria", "USA") |
{
"data": {
"CitiesByCountry": [
{
"id": 1,
"name": "Abuja",
"latitude": 9.05785,
"longitude": 7.49508,
"state_name": "Federal Capital Territory"
},
{
"id": 2,
"name": "Lagos",
"latitude": 6.45407,
"longitude": 3.39467,
"state_name": "Lagos"
}
]
}
}CitiesByState(state_name: String)Get all cities within a specific state.
| Argument | Type | Required | Description |
|---|---|---|---|
state_name | String | ✓ Yes | Name of the state (e.g., "Lagos", "California") |
{
"data": {
"CitiesByState": [
{
"id": 1,
"name": "Kumasi",
"latitude": 6.6666,
"longitude": -1.6163,
"country_name": "Ghana"
},
{
"id": 2,
"name": "Obuasi",
"latitude": 6.2012,
"longitude": -1.6912,
"country_name": "Ghana"
}
]
}
}City(name: String)Get detailed information about a specific city by name.
| Argument | Type | Required | Description |
|---|---|---|---|
name | String | ✓ Yes | Name of the city (e.g., "Toronto", "Lagos") |
{
"data": {
"City": {
"id": 1,
"name": "Kumasi",
"latitude": 6.6666,
"longitude": -1.6163,
"state_name": "Ashanti",
"country_name": "Ghana"
}
}
}Get countries by region with specific fields
{
CountriesByRegion(region: "Oceania") {
id
iso2
name
emoji
capital
currency
phone_code
}
}Get states within a country
{
StatesByCountry(country_name: "Nigeria") {
id
name
latitude
longitude
}
}Get cities by state
{
CitiesByState(state_name: "Lagos") {
id
name
latitude
longitude
country_name
}
}This project is open source and contributions are welcome! Whether it's adding new data, improving performance, or fixing bugs — feel free to submit a pull request.
MIT License — Free for personal and commercial use. Data provided as-is with no warranties. Attribution appreciated but not required. Original country/state/city data sourced from the countries-states-cities-database by Darshan Gada.
