> 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/searching-by-location/find-events-by-country-code.md).

# Find events by country code

For this example, we will find public and school holidays for the United States of America in 2018.

The Events endpoint allows you to specify a particular country by using the `country` parameter. This parameter supports the standard two-character ISO 3166-1 country codes. See the full list of [ISO 3166-1 alpha-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

We use this parameter to find all *holidays*, `category=public-holidays,school-holidays`, which are happening in the *United States of America (US)*, `country=US`, in *2018*, `active.gte=2018-01-01&active.lte=2018-12-31`:

```python
import requests

response = requests.get(
    url="https://api.predicthq.com/v1/events/",
    headers={
      "Authorization": "Bearer $API_TOKEN",
      "Accept": "application/json"
    },
    params={
        "country" : "US",
        "active.gte" : "2018-01-01",
        "active.lte" : "2018-12-31",
        "category" : "public-holidays,school-holidays"
    }
)

print(response.json())
```

One thing you might notice in the results are multiple events with the same title - this can happen when an event applies to multiple locations or occurs at different times. For example, a public holiday might apply to a number of states but not to the whole country - in this case there would be an event per state. A good indication of what area the event applies to is the `scope` field in the event information. If the event applies to the whole country this value is `country`, otherwise it may be `region`.

The following snippet shows the results:

```json
{
  "count": 468,
  "results": [
    {
      "id": "b6ca61ff6041c05d1e",
      "title": "New Year's Eve",
      "category": "public-holidays",
      ...
    }
  ]
}
```

That’s helpful, but doesn’t tell us which region the event applies to. Using the `place_hierarchies` field in event results we can get more detailed information about the place(s) the event applies to. Each hierarchy is an array of Place IDs, e.g. `["6295630","6255149","6252001","5165418"]` which is *Earth > North America > United States > Ohio*.

We can use the Places endpoint to find information about the Place IDs mentioned in the hierarchy or use the [Understanding place hierarchies](/getting-started/guides/geolocation-guides/understanding-place-hierarchies.md) guide.


---

# 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/searching-by-location/find-events-by-country-code.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.