> 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/overview.md).
# Overview
Geographic information for an event describes where the event is located and the geographic area impacted. This page introduces geographic information available in events:
Field
Description
geo.geography
Geo data in GeoJSON format for the area impacted by the event.
place_hierarchies and scope
Place where the event is located.
Events also have the `formatted_address` field for [venue entities](/getting-started/predicthq-data/entities.md) with the street address of an event where it is present.
{% hint style="info" %}
The `location` field is deprecated. Use the `geo` field for geographic information.
{% endhint %}
## **Points and areas**
Latitude and longitude coordinates represent a point event's location. An example is this [MLB game](https://events.predicthq.com/events/97iX53YAGnCwF9TGx3) located at `37.77859,-122.38926`.
Area events impact a geographic area such as a region, or an entire country. For example, [Christmas Day in the United Kingdom](https://events.predicthq.com/events/KmzdXpxZEq9M), is a country-wide public holiday.
A polygon can represent area events. The example image shows this [flood warning](https://events.predicthq.com/events/24gdWYbR9M7DzJBVdY) for several rivers in Mississippi, USA.
Our APIs offer spatial search parameters to discover all events that impact your locations of interest.
## Basic location
The `geo` field in the Events API response contains the longitude and latitude for point events. The following is an example of the location information for point events in the `geo` field. For a point type geometry object the coordinates are in the order longitude, latitude (as this follows the [geojson standard](https://geojson.org/)). Here is an example:
```
"geo": {
"geometry": {
"coordinates": [
-88.9746153,
30.393504
],
"type": "Point"
},
...
},
```
{% hint style="info" %}
In the `geo.geometry` field we follow the GeoJSON standard which orders coordinates as longitude followed by latitude (i.e., `[longitude, latitude]`).
{% endhint %}
For a point event, its `location` coordinates are where the event occurs. This may be the location of a venue. For example, a [San Francisco Giants MLB game at Oracle Park](https://events.predicthq.com/events/97iX53YAGnCwF9TGx3) has a latitude and longitude of `-122.38926979999997, 37.7785951`, which corresponds to the address of Oracle Park, 24 Willie Mays Plaza.
For an area event that does not have a polygon, its coordinates are the center of the area where the event occurs.
Area events cover either a Geonames Place, for example [Thanksgiving Day](https://events.predicthq.com/events/gEkxDPqErD5n), or a specific geographic area bounded by a geometry (polygon). The next section details geometries and polygons, additional geometric data available in the `geo` field for area events. See [GeoJSON ](#geojson)for more information.
#### Location field (deprecated)
The `location` field was previously used for latitude and longitude information. The `location` field's value contains coordinates in [GeoJSON](https://geojson.org/) order: `[longitude, latitude]`. Note the `geo` field is preferred over the `location` field because the `location` field is deprecated.
## Address data in the geo field
The `geo` field also contains address information. The **address** subfield within the `geo` field can contain the following information:
* `country_code` (required) - two-letter country code
* `formatted_address` (optional) - a fully formatted address which can include street address, locality, postcode, region, and country
* `postcode` (optional)
* `locality` (optional) - indicates the city or town the event occurs in
* `region` (optional) - the region or state at which the event takes place
For attended events when they are linked to a [venue entity](/getting-started/predicthq-data/entities.md#venue) then the address information corresponds to the address of the venue.
Events that cover a larger area (for example non-attended events like holidays) tend to have less address information. For example, a country-wide holiday may only have the country code field in the address field.
This later example shows the address subfield within the `geo` field:
```json
"geo": {
"geometry": {
"coordinates": [
-88.9746153,
30.393504
],
"type": "Point"
},
"placekey": "@8f4-wyy-4y9",
"address": {
"country_code": "US",
"formatted_address": "2350 Beach Blvd, Biloxi, MS 39531, USA",
"postcode": "39531",
"locality": "Biloxi",
"region": "Mississippi"
}
},
```
## GeoJSON
The `geo` field contains geometry information about an event's location in [GeoJSON](https://geojson.org/) format. Point events have a Point-type geometry, with the coordinates of the event's location (same as the `location` field). Area events may have Polygon or MultiPolygon-type geometries representing the specific area impacted by the event.
Where an area event has a Point-type geometry, it means the event applies to the Geonames Place of the event. The following response shows an event with a Polygon geometry:
```json
{
"count": 1,
"results": [
{
"id": "268aCtdaPgDJNurMeP",
"title": "Flood Warning",
"geo": {
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-94.15, 39.1599999],
[-94.17, 39.220000000000006],
[-93.86, 39.25000000000001],
[-93.84, 39.18000000000001],
[-94.05, 39.11000000000001],
[-94.15, 39.1599999]
]
]
}
}
// other fields omitted...
```
The example event snippet is a [flood warning in Missouri](https://events.predicthq.com/events/268aCtdaPgDJNurMeP). The GeoJSON data in the `geo.geometry` field can be plotted using tools that accept GeoJSON such as [geojson.io](https://geojson.io/). All our events with a Polygon or MultiPolygon display the geometry's shape when viewed in our [WebApp](https://control.predicthq.com/search/events/268aCtdaPgDJNurMeP) or our [Public Event page](https://events.predicthq.com/events/268aCtdaPgDJNurMeP). The following image plots the flood warning event's geometry.
The following image shows an example of an [event with a MultiPolygon geometry](https://events.predicthq.com/events/8qbpLh7PDjK3Crpj6b); you can see it has two polygons for one event.
We provide examples and code snippets to plot polygons in a Jupyter notebook in our [Severe-Weather Events Data Exploration](https://github.com/predicthq/phq-data-science-docs/blob/master/severe-weather-events/part_2_data_exploration.ipynb) notebook.
### Simplified polygons
Our raw polygon sources can have extremely detailed geometries which result in large GeoJSON filesizes. Polygons of this nature aren't practical to use for individual events either in the PredictHQ API or a customer's data lake. The complexity of such polygons often result from capturing geographic features that aren't relevant for practical use cases in determining the impact of an event (for example small bodies of water, or small unpopulated islands off a coast).
For this reason, we may pre-process polygons to simplify them to reduce the number of points. This results in smoothing out the shape while retaining the key boundaries of the geographic area of impact.
In the example images, the first polygon is part of a raw polygon before simplification; the second is after simplification. The original GeoJSON data contained about 18000 coordinate points (the JSON data for this alone is around 700kb) to accurately outline individual offshore land masses.
Raw polygon before simplification
Polygon after simplification
---
# 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/overview.md?ask=&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.
