DOCSEARCHbyAlgolia
Submit Docs

GeoGraphQL API Documentation

website·Indexed 30 days ago

https://geographql.netlify.app

A GraphQL API for retrieving information about countries, cities, and states. The API features cursor-based pagination and provides detailed queries for geographic data, including timezone information and regional filtering. Documentation covers query costs, rate limits, and specific input objects for filtering geographic entities.

Tokens
4.5K
Snippets
25
Records
41
Agent score
73%

What's inside GeoGraphQL

  1. Query state information using the State object

    The State object provides detailed information about a specific state, including its unique identifier, name, state code, and geographic coordinates. It also provides a relationship to the parent country via country_id and country_code (ISO Alpha-2). The cities field allows for retrieving a list of cities within that state, acting as a pre-filtered version of the general cities query.
    # Example query for state details
query {
  state(id: "123") {
    id
    name
    state_code
    country_id
    country_code
    latitude
    longitude
    cities {
      edges {
        node {
          name
        }
      }
    }
  }
}

  2. Reference the Country object fields

    The Country object provides comprehensive information about a country, including identification codes, geographic data, and regional associations.

    Key fields include:

    • Identification: id (Int), iso2 (ID, Alpha-2), iso3 (ID, Alpha-3), numeric_code (ID, ISO numeric), and phone_code (ID).
    • Geography & Location: latitude (Float), longitude (Float), region (String), subregion (String), and timezones (List of Timezone objects).
    • General Info: name (String), native (String), capital (String), currency (String), currency_symbol (String), tld (String), and emoji/emojiU (String).
    • Translations: translations (JSONObject) containing the country's name in multiple languages.
    • Relations:
      • states: Returns a StateConnection. This is equivalent to the states query but pre-filtered for the specific country.
      • cities: Returns a CityConnection. This is equivalent to the cities query and supports filtering via CountryCitiesFilterInput.

  3. Reference Timezone object fields in GeoGraphQL

    The Timezone object provides detailed information about a specific timezone, including its name, GMT offset, and associated country identifier. The following fields are available:

    • zone_name (String!): The zone name.
    • gmt_offset (Int!): The Greenwich Mean Time offset in seconds.
    • gmt_offset_name (Int!): Greenwich Mean Time offset name.
    • abbreviation (String!): The abbreviation of the timezone name.
    • timezone_name (String!): The name of the timezone.
    • country_id (Int!): The ID of the country associated with the timezone.

  4. City object fields reference

    The City object provides detailed geographical and administrative information about a city, including its unique identifier, name, coordinates, and the IDs and codes of its parent state and country.
    type City {
  id: Int!
  name: String!
  state_id: Int!
  state_code: String!
  country_id: Int!
  country_code: String!
  latitude: Float!
  longitude: Float!
}

  5. Implement GraphQL Cursor-Based Pagination

    The API implements cursor-based pagination following the GraphQL Cursor Connections Specification. This approach is used to efficiently navigate large datasets by using cursors to identify the position of a record relative to others.

  6. Understand API Rate Limiting

    The API employs a point-based rate-limiting system to prevent malicious overuse and ensure service stability.

  7. Calculate Requested Query Cost for GeoGraphQL queries

    The requested query cost is the maximum possible cost of a query, calculated by multiplying the requested page sizes of nested fields.

    For a simple query, the cost is equal to the first parameter of the top-level field. For nested queries, the cost is the sum of the top-level request plus the product of all preceding page sizes in the hierarchy.

    # Example Nested Query
{
  countries(page: { first: 10 }) {
    edges {
      node {
        states(page: { first: 5 }) {
          edges {
            node {
              cities(page: { first: 3 }) {
                totalCount
              }
            }
          }
        }
        cities(page: { first: 5 }) {
          totalCount
        }
      }
    }
  }
}

    Calculation:

    10 (Countries)

    • 50 (10 Countries * 5 States)
    • 150 (10 Countries * 5 States * 3 Cities)
    • 50 (10 Countries * 5 Cities) = 260 Total Points

  8. Configure arguments for the cities query

    The cities query accepts the following arguments to refine the result set:

    • filter: A CityFilterInput object used to specify city filter criteria.
    • pagination: A PaginationInput object used to control the number of results and the starting point for the list.

  9. Configure arguments for the countries query

    The countries query accepts the following arguments:

    • filter: A CountryFilterInput object used to filter the returned countries (e.g., by subregion).
    • pagination: A PaginationInput object used to control the result set size and offset.

  10. Avoid unsupported PaginationInput combinations

    When using pagination inputs, certain combinations of arguments are invalid and will not be supported. Ensure your queries adhere to these constraints to avoid errors:
    ❌ Invalid Combinations:
- first AND last
- first AND before
- last AND after
- last WITHOUT before

  11. Use StateCountryCode input to identify a specific state

    The StateCountryCode input object is used to find a specific state by providing both the state's unique code and the code of the country where that state is located. Both fields are required strings.
    input StateCountryCode {
  state_code: String!
  country_code: String!
}

  12. Retrieve a specific country using the country query

    Use the country query to fetch a single country record. You can identify the country using any one of the following arguments: id (Integer), iso2 (ISO Alpha-2 two-letter code), iso3 (ISO Alpha-3 three-letter code), or numeric_code (ISO numeric three-digit code). The query returns a Country object.
    {
  country(iso3: "USA") {
    id
    name
    iso2
    capital
    tld
    currency
    currency_symbol
    emoji
    states(page: { first: 2 }) {
      totalCount
      edges {
        cursor
        node {
          id
          name
        }
      }
    }
  }
}