Deliberate API
Developer Portal

Core Concepts

Deliberate API exposes geographic information as a collection of sets where each set has tags, properties, and relationships. Understanding these primitives makes it easier to compose powerful queries.

Definitions

A set is a collection of cells representing a geographic area (for example, a U.S. state, county, or national park).

json
{
    "uuid": "80a25c7e-f0de-4be0-be9d-6826ac63c792",
    "tags": [
        {
            "uuid": "a3256487-56a0-44e2-971d-fbfb55e2c83e",
            "name": "us_national_park"
        }
    ],
    "properties": {
        "name": "Zion National Park",
        "unit_code": "ZION",
        "unit_type": "National Park",
        "gnis_feature_id": "1455157"
    }
}

Tags

A tag is an arbitrary string attached to a set that categorizes it. For example, us_state or us_county. Think of this as a bucket that can contain many sets.

Properties

A property is a key–value pair attached to a set. For example, the name of a state or the population of a country.

Important:
A property is not the place to store informationa about how a geographical area (set) is related to another geographical area (set). For example, you could have a set that is suppose to represent a state. Developing this model I was tempted to add a country property to the state set (country: "United States") so later we would know what country the state is in. This idea of a grographical area being related to another grographical area is called a relationship and is a first class concept in Deliberate API.

json
"properties": {
  "name": "Zion National Park",
  "unit_code": "ZION",
  "unit_type": "National Park",
  "gnis_feature_id": "1455157"
}

Relationships

Sets are not isolated—they can be linked with relationships. This lets us model real-world containment or association, like a state being part of a country.

Relationship Types:
  • SUBSET: Set A is completely contained within Set B
  • INTERSECTS: Set A shares some area with Set B

Relationships also have direction. Just because Set A is a subset of Set B does not mean that Set B is a subset of Set A. These are the directions currently supported:


Relationship Directions:
  • OUTBOUNDFrom current set to target set
  • INBOUNDFrom target set to current set
  • ANYEither direction

Lets use the relationship type SUBSET and direction OUTBOUND to find all national parks in the state of Utah. First we find the state of Utah through the tag us_state and the property name set to Utah. Then we find all sets that are a subset of the state of Utah. This is done by using the relationships filter with the SUBSET type and outbound direction. Finally we filter for sets tagged with us_national_park.
json
{
  "where": {
    "tags": { "contains": "us_national_park" },
    "relationships": {
      "type": "SUBSET",
      "direction": "outbound",
      "to": {
        "tags": { "contains": "us_state" },
        "properties": { "name": { "eq": "Utah" }
      }
    }
  }
}

Next lets use the relationship type INTERSECT and direction any to find all the states that the Appalachian Trail intersects with. First we find the set that is tagged with appalachian_trail. Then we find all sets that intersect with the Appalachian Trail. This is done by using the relationships filter with the INTERSECTS type and any direction.
json
{
  "where": {
    "tags": { "contains": "us_state" },
    "relationships": {
      "type": "INTERSECTS",
      "direction": "any",
        "to": {
          "tags": { "contains": "us_national_scenic_trail" },
          "properties": { "name": {"eq": "Appalachian National Scenic Trail"}}
      }
    }
  }
}