GeoDB Cities API

Response Format

GeoDB adheres closely to the Relay.dev specification for paging results within the graph. Specifically, graph nodes that represent collections are implemented as Connections, whereby each connection has the following structural form:

connection {
  edges [
    { cursor1, node1 },
    { cursor2, node2 }
    ...
  ]
  totalCount
  pageInfo {
    startCursor
    endCursor
    hasPreviousPage
    hasNextPage
  }
}

Where:

• A cursor is an opaque id that represents a specific offset into the results.
• A node is some element in the results.
• An edge represents a specific result node along with the cursor referencing where that node occurs in the results.
• totalCount represents the total number of results, irrespective of the current page.
• pageInfo.startCursor/endCursor represent the offset of the first/last element in the current results page.

Notes:

• The first and last arguments will be relative to the start and end, respectively, of the total results available on a given connection node (or relative to the after and before cursors, if specified). This means it's possible for the corresponding first and last slices to intersect. In this case, GeoDB returns a union of the two slices. This slightly departs from the official Relay.dev spec, but we think it makes more sense.
• Your query may be rejected with an HTTP 403 Forbidden if you attempt to request too many connection node results in one shot. Specifically, for a query with path node1/node2/node3, GeoDB calculates your number of requested results as node1 (first + last) * node2(first + last) * node3(first + last) and checks that this doesn't exceed the maximum allowed value under your plan. For example, if your plan allows paging up to 1000 results:
  • OK
    • countries(first:1)/regions(first:1)/populatedPlaces(first:1000) -> 1*1*1000
    • countries(first:10)/regions(first:10)/populatedPlaces(first:10) -> 10^3
    • countries(first:10)/regions(first:100)/populatedPlaces(first:1) -> 10*100*1
  • Exceeds 1000
    • countries(first:100)/regions(first:100)/populatedPlaces(first:100) -> 100^3
    • countries(first:1000)/regions(first:1)/populatedPlaces(first:2) -> 1000*1*2

Response Format

Any collection request will have the following basic response format:

{
  metadata: {
    currentOffset: ZERO_BASED_INDEX_OF_THE_FIRST_RESULT,
    totalCount: TOTAL_NUMBER_OF_RESULTS
  }
  results: [
    {
      result1
    },
    {
      result2
    },
    ...
  ]
}

Pagination Links

If you are making a collection request and the number of results exceeds the requested limit (page size), you will see the following additional elements in the response:

{
  ...
  "links":[
    {
      "rel":"first",
      "href":"/link/to/first/page/of/results"
    },
    {
      "rel":"prev",
      "href":"/link/to/previous/page/of/results"
    },
    {
      "rel":"next",
      "href":"/link/to/next/page/of/results"
    },
    {
      "rel":"last",
      "href":"/link/to/last/page/of/results"
    }
  ]
}

These links adhere to the HATEOAS format and should be self-explanatory.

Notes:

• The prev/next links will be generated if contextually appropriate. Meaning, there will be no prev or next if you're already on the first or last page, respectively.
• Specifying an offset that goes beyond the last page of results will simply return the last page of results.
• Specifying a limit that exceeds the maximum limit allowed under your plan will result in an HTTP 403 Forbidden.
• You may optionally turn off HATEOAS link generation by setting the hateoasMode request parameter to false. See the API docs for details.