Below is a cookbook of things you might want do with the GeoDB Cities GraphQL API.

All examples can be executed from the shell using cURL, as follows:

curl --request POST \
     --url https://geodb-cities-graphql.p.rapidapi.com/ \
     --header 'content-type: application/json' \
     --header 'x-rapidapi-host: geodb-cities-graphql.p.rapidapi.com' \
     --header 'x-rapidapi-key: YOUR_API_KEY' \
     --data '{"query":"QUERY"}'

Get country states, provinces, and top-level districts

Get the regions for some country.

{
  country(id:"COUNTRY_ID") {
    regions(first:10) {
      totalCount
      pageInfo {
        startCursor
        endCursor
        hasNextPage
      }
      edges {
        node {
          isoCode
          wikiDataId
          name
        }
      }
    }
  }
}

Where:

• COUNTRY_ID: An ISO-3166 country code or Wikidata ID

Get country region cities

Get the cities for some country and region.

{
  country(id:"COUNTRY_ID") {
    region(code:"REGION_CODE") {
      populatedPlaces(types:["CITY"], first:10) {
        totalCount
        pageInfo {
          startCursor
          endCursor
          hasNextPage
        }
        edges {
          node {
            id
            wikiDataId
            name
          }
        }
      }
    }
  }
}

Where:

• COUNTRY_ID: An ISO-3166 country code or Wikidata ID
• REGION_CODE: An ISO-3166 region code or Wikidata ID

If you want both cities and admin-divisions, simply omit the types argument.

Get the metropolitan area for a GPS location

Get the largest city within 20 miles of a GPS location.

{
  populatedPlaces(
    types:["CITY"],
    location:{latitude:LATITUDE, longitude:LONGITUDE}
    radius:20
    distanceUnit:MI
    sort:"-population"
    first:1
  ) {
    edges {
      node {
        id
        name
        population
      }
    }
  }
}

Where:

• LATITUDE: -90 to 90 (±DD.DDDD)
• LONGITUDE: -180 to 180 (±DD.DDDD)

Get a city’s surrounding neighborhoods

Get all cities with a max population of 100000 within 20 miles of some city.

{
  populatedPlace(id:"CITY_ID") {
    nearbyPopulatedPlaces(
      types:["CITY"], 
      maxPopulation:100000
      radius:20
      distanceUnit:MI
      first:10
    ) {
      totalCount
      pageInfo {
        startCursor
        endCursor
        hasNextPage
      }
      edges {
        node {
          id
          name
          population
        }
      }
    }
  }
}

Where:

• CITY_ID: The city’s native id or Wikidata ID

If you want both cities and admin-divisions, simply omit the types argument.

Get the distance between two cities

{
  populatedPlace(id:"FROM_CITY_ID") {
      distance(toPlaceId:"TO_CITY_ID", distanceUnit:MI)
  }
}