> For the complete documentation index, see [llms.txt](https://docs.predicthq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.predicthq.com/getting-started/guides/geolocation-guides/understanding-place-hierarchies.md).

# Understanding place hierarchies

{% hint style="info" %}
Places associated with our events are [Geonames](https://www.geonames.org/) Features, which can be either an Area, an Administrative Feature, or a Populated Place. Use our [Places API](/api/places/search-places.md) to explore Places data used in our events.
{% endhint %}

The `place_hierarchies` field contains Place ids for an event. The structure is an array of array of ids; ids are strings. For example:

```json
[
  ["6295630", "6255149", "6252001", "5815135", "5799783", "5786882"]  
]
```

The array of ids is ordered, representing a parent-to-child hierarchy of places. In the earlier example, the id 6295630 is the parent place of 6255149; and 6255149 is the parent place of 6252001, and so on. The last id in the list is the place in which the event occurs: 5786882 in the example.

Details for each Place, such as its name can be retrieved from the [Places API](/api/places/search-places.md). For the earlier hierarchy, calling the Places API with `?id=6295630,6255149,6252001,5815135,5799783,5786882` returns:

```json
{
  "count": 6,
  "results": [ // some fields omitted
    {"id": "6295630", "type": "planet", "name": "Earth"},
    {"id": "6255149", "type": "continent", "name": "North America"},
    {"id": "6252001", "type": "country", "name": "United States"},
    {"id": "5815135", "type": "region", "name": "Washington"},
    {"id": "5799783", "type": "county", "name": "King County"},
    {"id": "5786882", "type": "locality", "name": "Bellevue"}
  ]
```

This reveals an event with the earlier `place_hierarchy` occurs in Bellevue, which belongs to King County, which is in Washington state, USA.

The `place_hierarchy` value when understood with the `scope` of an event reveals if an event is a point event or an area event. Point events have a `scope` value "locality"; Area events have "localadmin", "county", "region", or "country".

Point events happen at a point (its coordinate location) in the locality-level place it is scoped to. Example: This [MLB game at Oracle Park](https://events.predicthq.com/events/97iX53YAGnCwF9TGx3) is a point event with `scope`value "locality" and `place_hierarchy` value `[["6295630","6255149","6252001","5332921","5391997","5391959"]]`. 5391959 is the place id of San Francisco City.

Area events without polygons apply to the place it is scoped to, which is either a county-level, region-level, or country-level place. Example: This [Thanksgiving Day](https://events.predicthq.com/events/gEkxDPqErD5n) holiday is an area event with `scope` value "country" and `place_hierarchy` value `[["6295630","6255149","6252001"]]`. 6252001 is the place id of the United States.

Area events with polygons apply to the area the polygon's geometry defines. Places in the event's `place_hierarchies` are those which overlap with the polygon.

Place hierarchies value can be an empty array in some cases.

## Multiple hierarchies

Some events can have multiple hierarchies.

Point events can have up to two hierarchies. The second hierarchy, if it exists, is a nearby major city's hierarchy within a radius of 50km. This [Bite of Seattle community festival](https://events.predicthq.com/events/QDgCysY3kMnpoGYFi9), for example, is scoped to two places. Its `scope` and `place_hierarchies` values are shown later. 7153941 is the place id of Denny Regrade, the neighborhood where the festival takes place; 5809844 is the place id of Seattle, a nearby major city. `{ "scope": "locality", "place_hierarchies": [ ["6295630", "6255149", "6252001", "5815135", "5799783", "7153941"], ["6295630", "6255149", "6252001", "5815135", "5799783", "5809844"] ] }`

Area events have multiple hierarchies if the event applies to multiple counties or regions, or if its polygon overlaps with multiple counties or regions. For example: this [flood warning](https://events.predicthq.com/events/24gdWYbR9M7DzJBVdY) event's polygon overlaps with three counties in the state of Mississippi. Its `scope` and `place_hierarchies` values are shown later. 4421859, 4429877, 4450285 are the respective place ids for Claiborne County, Hinds County, and Warren County, as the following values show:

```json
{
  "scope": "county",
  "place_hierarchies": [
    [
      "6295630",
      "6255149",
      "6252001",
      "4436296",
      "4421859"
    ], [
      "6295630",
      "6255149",
      "6252001",
      "4436296",
      "4429877"
    ], [
      "6295630",
      "6255149",
      "6252001",
      "4436296",
      "4450285"
    ]
  ]
}
```

## Examples

### Fetch place information for place IDs

With a given list of Place IDs, fetch the Place info using the [Places endpoint](/api/places/search-places.md), as in this code:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/places/",
    headers={
        "Authorization": "Bearer $API_TOKEN",
        "Accept": "application/json",
    },
    params={
        "id": "5391959,6252001,7153941,5809844,4421859,4429877,4450285",
    }
)

print(response.json())
```

The response looks like:

```json
{
  "count": 7,
  "results": [ // some fields omitted
    {
      "id": "5391959",
      "type": "locality",
      "name": "San Francisco",
      "country_alpha2": "US",
      "location": [-122.41942, 37.77493]
    },
    {
      "id": "6252001",
      "type": "country",
      "name": "United States",
      "country_alpha2": "US",
      "location": [-98.5, 39.76]
    },
    {
      "id": "7153941",
      "type": "locality",
      "name": "Denny Regrade",
      "country_alpha2": "US",
      "location": [-122.33667, 47.61611]
    },
    {
      "id": "5809844",
      "type": "locality",
      "name": "Seattle",
      "country_alpha2": "US",
      "location": [-122.33207, 47.60621]
    },
    {
      "id": "4421859",
      "type": "county",
      "name": "Claiborne County",
      "country_alpha2": "US",
      "location": [-90.91181, 31.97369]
    },
    {
      "id": "4429877",
      "type": "county",
      "name": "Hinds County",
      "country_alpha2": "US",
      "location": [-90.44282, 32.2667]
    },
    {
      "id": "4450285",
      "type": "county",
      "name": "Warren County",
      "country_alpha2": "US",
      "location": [-90.85201, 32.35723]
    }
  ]
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.predicthq.com/getting-started/guides/geolocation-guides/understanding-place-hierarchies.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.