Geographic information and Polygons

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.

Below is an example of an event with a MultiPolygon geometry; 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 notebook.

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.

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.

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.

Place hierarchy

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"] ] }