Geographic information and Polygons

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
location Latitude and longitude coordinates of the event's location.
geo Geometric data 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 with the street address of an event where it is present.

Events can occur at a point or cover an area.

Point events' locations are represented by latitude, longitude coordinates. An example is this MLB game located at 37.7785951,-122.38926979999997.

Area events impact a geographic area such as a region, or an entire country. For example, Christmas Day in the United Kingdom, is a country-wide public holiday.

Area events can be represented by a polygon. The example image shows this flood warning for several rivers in Mississippi, USA.

alt

Our APIs offer spatial search parameters to discover all events that impact your locations of interest. How events with points, places, or polygons can be queried is shown in the sections below.

Location of an event

The location field's value contains coordinates in GeoJSON order: [longitude, latitude].

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 has the location value [-122.38926979999997, 37.7785951], which corresponds to the address of Oracle Park, 24 Willie Mays Plaza.

For an area event, its location coordinates are the center of the area where the event occurs. For example, a nation-wide public holiday in the USA, such as Thanksgiving Day, has the location value [ -95.712891, 37.09024 ] which is the centroid of the Geonames Place for the country of USA.

Area events cover either a Geonames Place, as in the Thanksgiving Day example above, 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.

Geometry and polygons

The geo field contains geometry information about an event's location in GeoJSON format. Point events will 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 example event snippet is a flood warning in Missouri. The GeoJSON data in the geo.geometry field can be plotted using tools that accept GeoJSON such as geojson.io. All our events with a Polygon or MultiPolygon will display the geometry's shape when viewed in Control Center or our Public Event page. A plot of the flood warning event's geometry is shown below.

alt

Below is an example of an event with a MultiPolygon geometry; you can see it has two polygons for one event.

alt

We provide examples and code snippets to plot polygons in a Jupyter notebook in our Severe-Weather Events Data Exploration notebook.

curl -X GET "https://api.predicthq.com/v1/events/?268aCtdaPgDJNurMeP" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

Example event snippet

{
  "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...

Handling large and complex 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.

alt
alt

Finding events that impact a location

Performing a radial search using our Events API's within parameter is a common way to find events that impact your locations of interest. See our guide on radial searches and the within search parameter.

Which events are returned by a radial search depends on their location and geometry type. The image below shows the result of the example radial search performed in Control Center: A 4-mile radius around a point in Brooklyn, New York, USA - the search area is the blue circle.

LOCATION AND GEOMETRY TYPE RADIAL SEARCH MATCHING CRITERION
Point event with Point geometry Returned if their point falls within the specified radius. In the image below, matching point events are the dots within the blue circle.
Area event with Polygon or MultiPolygon geometry Returned if any part of the polygons intersect with the specified radius. In the image below, matching events with polygons intersect with the blue circle.
Area event with Point geometry Returned if the radial search location (the provided lat,lon coordinates regardless of radius) is a child place of the area event's place. In the image below, the dot outside the blue circle is an area event without a polygon. This event covers all of New York City, and since the radial search's location is in Brooklyn, a child place of New York City, this area event was returned also.
alt

We recommend that if you are looking for events around a location like a store, hotel, or other bricks and mortar location, you use a radial search (a within query) to find events that impact you.

In order to set your radius we recommend using the Suggested Radius API. Call the Suggested Radius API and supply the latitude and longitude of the location and use that radius to look for events around a location. The Suggested Radius API is powered by a machine learning model that looks at factors like population density, the events around a location, the customer’s industry, and many other factors to determine the ideal radius.

You can also search for events occurring, in particular, Geonames Places using the place.scope parameter with Place ids. In our Severe-Weather Events Data Engineering notebook, we provide code examples to find Place ids for your locations of interest.

Events have a place_hierarchies field which contains the ids of Places an event occurs in or area it covers. This field is explained in the next section.

Example radial search

curl -X GET -G "https://api.predicthq.com/v1/events/" \
     -d active.gte=2020-08-06 \
     -d active.lte=2020-09-05 \
     -d within=4mi@40.6441,-73.9393 \
     -H "Authorization: Bearer $ACCESS_TOKEN"

Example using suggested radius to find the radius to use in the radial search

curl -X GET https://api.predicthq.com/v1/suggested-radius?location.origin=37.747767,-122.455320&industry=parking&radius_unit=km \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN"

Place hierarchy

Places associated with our events are Geonames Features, which can be either an Area, an Administrative Feature, or a Populated Place. Use our Places API to explore Places data used in our events.

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

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

The array of ids is ordered, representing a parent-to-child hierarchy of places. In the above 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. For the above hierarchy, calling the Places API with ?id=6295630,6255149,6252001,5815135,5799783,5786882 returns:

{
  "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 above 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 is a point event with scopevalue "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 will either be a county-level, region-level, or country-level place. Example: This Thanksgiving Day 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 defined by the polygon's geometry. 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, for example, is scoped to 2 places. Its scope and place_hierarchies values are shown below. 7153941 is the place id of Denny Regrade, the neighbourhood 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 event's polygon overlaps with 3 counties in the state of Mississippi. Its scope and place_hierarchies values are shown below. 4421859, 4429877, 4450285 are the respective place ids for Claiborne County, Hinds County, and Warren County.

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

Place detail snippets

curl -X GET -G "https://api.predicthq.com/v1/places/" \
     -d id=5391959,6252001,7153941,5809844,4421859,4429877,4450285 \
     -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "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]
    }
  ]
}

Using polygons in your data lake

Our Events API uses polygons data in the geo.geometry field when searching to provide you with spatially relevant results. Once you have events with polygons, you can use them in your own systems. To do so, your systems will need to support GeoJSON and provide geospatial functionality.

Many datastores support GeoJSON and geospatial queries:

Using polygons with offline events' data

So far on this page, we have provided details on how to use our API to query for events with geo data (including polygons) that impact a given location. This section provides details for customers wanting to download our events' and do a geospatial operation on their polygons in the geo field. These operations could include filtering which polygons are impacting an area based on an offline sample of data or visualize them inside a Jupyter notebook. This section could be useful depending on what you're trying to do with the geo data, for instance, if you are a Data Scientists performing R&D the following instructions might come in handy. You can always use our data exporter to bulk download events data to CSV or JSONL format.

There are many tools and libraries available to help you process and visualize our polygon events. We have some examples in our Data Exploration notebook notebook which use GeoPandas and Folium libraries in Python to analyze and visualize polygons from our Severe-Weather Events.

You can use Shapely to parse the event's geometry field and load it as a sheply object. In the following example, we would take a sample event with polygon and load it's geometry field into a shapely Polygon. We also go through this example in our severe-weather datascience docs, so please check out Appendix 2: Parsing geojson with Shapely if you prefer a more interactive example.

from shapely.geometry import shape


event = {"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...
        }

# retrieving event's geojson field
event_geojson = event['geo']['geometry']

# parsing the geojson object using shape from shapely
parsed_polygon = shape(event_geojson)

# print the shapely polygon object
print(parsed_polygon)
>> POLYGON ((-94.15000000000001 39.1599999, -94.17 39.22000000000001, -93.86 39.25000000000001, -93.84 39.18000000000001, -94.05 39.11000000000001, -94.15000000000001 39.1599999))

Shapely has great built-in features, such as intersects which we would use to check if a given point (lat, lon) is inside the polygon:

from shapely.geometry import Point

# Define point_1 adn point_2 in (lon, lat) format with shapely's Point
point_1 = Point(-94.096, 39.165)
point_2 = Point(-93.819, 39.131)

# Checked whether the point_1 intersects with event's polygon
parsed_polygon.intersects(point_1)
>> True

# Checked whether the point_2 intersects with event's polygon
parsed_polygon.intersects(point_2)
>> False

As you can see in the picture below, point_1 is inside the polygon but point_2 is not:

alt

Coordinate Reference Systems

Both our API and Shapely use World Geodetic System 1984 (WGS84 also called EPSG:4326) to represent coordinates in a Polygon or Point object by default. If you want to do more complicated GeoSpatial operations on these coordinates beyond what we have discussed here, you might need to project these objects from WGS84 to another Coordinate Reference Systems (CRS) that fits your purpose.