Introducing the Forecasts API — Event-driven forecasts for precise demand planning. Fast, accurate, and easy to run.
Explore Now
LogoLogo
Visit websiteWebAppGet DemoTry for Free
  • Introduction
  • Swagger UI
  • Loop
  • System Status
  • Getting Started
    • API Quickstart
    • Data Science Notebooks
    • PredictHQ Data
      • Data Accuracy
      • Event Categories
        • Attendance-Based Events
        • Non-Attendance-Based Events
        • Unscheduled Events
        • Live TV Events
      • Labels
      • Entities
      • Ranks
        • PHQ Rank
        • Local Rank
        • Aviation Rank
      • Predicted Attendance
      • Predicted End Times
      • Predicted Event Spend
      • Predicted Events
      • Predicted Impact Patterns
    • Guides
      • Geolocation Guides
        • Overview
        • Searching by Location
          • Find Events by Latitude/Longitude and Radius
          • Find Events by Place ID
          • Find Events by IATA Code
          • Find Events by Country Code
          • Find Events by Placekey
          • Working with Location-Based Subscriptions
        • Understanding Place Hierarchies
        • Working with Polygons
        • Join Events using Placekey
      • Date and Time Guides
        • Working with Recurring Events
        • Working with Multi-day and Umbrella Events
        • Working with Dates, Times and Timezones
      • Events API Guides
        • Understanding Relevance Field in Event Results
        • Attendance-Based Events Notebooks
        • Non-Attendance-Based Events Notebooks
        • Severe Weather Events Notebooks
        • Academic Events Notebooks
        • Working with Venues Notebook
      • Features API Guides
        • Increase Accuracy with the Features API
        • Get ML Features
        • Demand Forecasting with Event Features
      • Forecasts API Guides
        • Getting Started with Forecasts API
        • Understanding Forecast Accuracy Metrics
        • Troubleshooting Guide for Forecasts API
      • Live TV Event Guides
        • Find Broadcasts by County Place ID
        • Find Broadcasts by Latitude and Longitude
        • Find all Broadcasts for an Event
        • Find Broadcasts for Specific Sport Types
        • Aggregating Live TV Events
        • Live TV Events Notebooks
      • Beam Guides
        • ML Features by Location
        • ML Features by Group
      • Demand Surge API Guides
        • Demand Surge Notebook
      • Guide to Protecting PredictHQ Data
      • Streamlit Demo Apps
      • Guide to Bulk Export Data via the WebApp
      • Industry-Specific Event Filters
      • Tutorials
        • Filtering and Finding Relevant Events
        • Improving Demand Forecasting Models with Event Features
        • Using Event Data in Power BI
        • Using Event Data in Tableau
        • Connecting to PredictHQ APIs with Microsoft Excel
        • Loading Event Data into a Data Warehouse
        • Displaying Events in a Heatmap Calendar
        • Displaying Events on a Map
    • Tutorials by Use Case
      • Demand Forecasting with ML Models
      • Dynamic Pricing
      • Inventory Management
      • Workforce Optimization
      • Visualization and Insights
  • Integrations
    • Integration Guides
      • Keep Data Updated via API
      • Integrate with Beam
      • Integrate with Loop Links
    • Third-Party Integrations
      • Receive Data via Snowflake
        • Example SQL Queries for Snowflake
        • Snowflake Data Science Guide
          • Snowpark Method Guide
          • SQL Method Guide
      • Receive Data via AWS Data Exchange
        • CSV/Parquet Data Structure for ADX
        • NDJSON Data Structure for ADX
      • Integrate with Databricks
      • Integrate with Tableau
      • Integrate with a Demand Forecast in PowerBI
      • Google Cloud BigQuery
    • PredictHQ SDKs
      • Python SDK
      • Javascript SDK
  • API Reference
    • API Overview
      • Authenticating
      • API Specs
      • Rate Limits
      • Pagination
      • API Changes
      • Attribution
      • Troubleshooting
    • Events
      • Search Events
      • Get Event Counts
    • Broadcasts
      • Search Broadcasts
      • Get Broadcasts Count
    • Features
      • Get ML Features
    • Forecasts
      • Models
        • Create Model
        • Update Model
        • Replace Model
        • Delete Model
        • Search Models
        • Get Model
        • Train Model
      • Demand Data
        • Upload Demand Data
        • Get Demand Data
      • Forecasts
        • Get Forecast
      • Algorithms
        • Get Algorithms
    • Beam
      • Create an Analysis
      • Upload Demand Data
      • Search Analyses
      • Get an Analysis
      • Update an Analysis
      • Partially Update an Analysis
      • Get Correlation Results
      • Get Feature Importance
      • Refresh an Analysis
      • Delete an Analysis
      • Analysis Groups
        • Create an Analysis Group
        • Get an Analysis Group
        • Search Analysis Groups
        • Update an Analysis Group
        • Partially Update an Analysis Group
        • Refresh an Analysis Group
        • Delete an Analysis Group
        • Get Feature Importance for an Analysis Group
    • Demand Surge
      • Get Demand Surges
    • Suggested Radius
      • Get Suggested Radius
    • Saved Locations
      • Create a Saved Location
      • Search Saved Locations
      • Get a Saved Location
      • Search Events for a Saved Location
      • Update a Saved Location
      • Delete a Saved Location
    • Loop
      • Loop Links
        • Create a Loop Link
        • Search Loop Links
        • Get a Loop Link
        • Update a Loop Link
        • Delete a Loop Link
      • Loop Settings
        • Get Loop Settings
        • Update Loop Settings
      • Loop Submissions
        • Search Submitted Events
      • Loop Feedback
        • Search Feedback
    • Places
      • Search Places
      • Get Place Hierarchies
  • WebApp Support
    • WebApp Overview
      • Using the WebApp
      • API Tools
      • Events Search
      • How to Create an API Token
    • Getting Started
      • Can I Give PredictHQ a Go on a Free Trial Basis?
      • How Do I Get in Touch if I Need Help?
      • Using AWS Data Exchange to Access PredictHQ Events Data
      • Using Snowflake to Access PredictHQ Events Data
      • What Happens at the End of My Free Trial?
      • Export Events Data from the WebApp
    • Account Management
      • Managing your Account Settings
      • How Do I Change My Name in My Account?
      • How Do I Change My Password?
      • How Do I Delete My Account?
      • How Do I Invite People Into My Organization?
      • How Do I Log In With My Google or LinkedIn Account?
      • How Do I Update My Email Address?
      • I Signed Up Using My Google/LinkedIn Account, but I Want To Log In With My Own Email
    • API Plans, Pricing & Billing
      • Do I Need To Provide Credit Card Details for the 14-Day Trial?
      • How Do I Cancel My API Subscription?
      • Learn About Our 14-Day Trial
      • What Are the Definitions for "Storing" and "Caching"?
      • What Attribution Do I Have To Give PredictHQ?
      • What Does "Commercial Use" Mean?
      • What Happens If I Go Over My API Plan's Rate Limit?
    • FAQ
      • How Does PredictHQ Support Placekey?
      • Using Power BI and Tableau With PredictHQ Data
      • Can I Download a CSV of Your Data?
      • Can I Suggest a New Event Category?
      • Does PredictHQ Have Historical Event Data?
      • Is There a PredictHQ Mobile App?
      • What Are Labels?
      • What Countries Do You Have School Holidays For?
      • What Do The Different Event Ranks Mean?
      • What Does Event Visibility Window Mean?
      • What Is the Difference Between an Observed Holiday and an Observance?
    • Tools
      • Is PHQ Attendance Available for All Categories?
      • See Event Trends in the WebApp
      • What is Event Trends?
      • Live TV Events
        • What is Live TV Events?
        • Can You Access Live TV Events via the WebApp?
        • How Do I Integrate Live TV Events into Forecasting Models?
      • Labels
        • What Does the Closed-Doors Label Mean?
    • Beam (Relevancy Engine)
      • An Overview of Beam - Relevancy Engine
      • Creating an Analysis in Beam
      • Uploading Your Demand Data to Beam
      • Viewing the List of Analysis in Beam
      • Viewing the Table of Results in Beam
      • Viewing the Category Importance Information in Beam
      • Feature Importance With Beam - Find the ML Features to Use in Your Forecasts
      • Beam Value Quantification
      • Exporting Correlation Data With Beam
      • Getting More Details on a Date on the Beam Graph
      • Grouping Analyses in Beam
      • Using the Beam Graph
      • Viewing the Time Series Impact Analysis in Beam
    • Location Insights
      • An Overview of Location Insights
      • How to Set a Default Location
      • How Do I Add a Location?
      • How Do I Edit a Location?
      • How Do I Share Location Insights With My Team?
      • How Do I View Details for One Location?
      • How Do I View My Saved Locations as a List?
      • Search and View Event Impact in Location Insights
      • What Do Each of the Columns Mean?
      • What Is the Difference Between Center Point & Radius and City, State, Country?
Powered by GitBook

PredictHQ

  • Terms of Service
  • Privacy Policy
  • GitHub

© 2025 PredictHQ Ltd

On this page
  • Points and Areas
  • Basic Location
  • Address data in the geo field
  • GeoJSON
  • Simplified Polygons

Was this helpful?

  1. Getting Started
  2. Guides
  3. Geolocation Guides

Overview

PreviousGeolocation GuidesNextSearching by Location

Last updated 1 month ago

Was this helpful?

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 with the street address of an event where it is present.

The location field was previously used for geographic information but is now deprecated.

Points and Areas

Point events' locations are represented by latitude, longitude coordinates. An example is this located at 37.77859,-122.38926.

Area events impact a geographic area such as a region, or an entire country. For example, , is a country-wide public holiday.

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

Our APIs offer spatial search parameters to discover all events that impact your locations of interest.

Basic Location

    "geo": {
        "geometry": {
            "coordinates": [
                -88.9746153,
                30.393504
            ],
            "type": "Point"
        },
    ...
    },

In the geo.geometry field we follow the GeoJSON standard which orders coordinates as longitude followed by latitude (i.e., [longitude, latitude]).

For an area event that does not have a polygon, its coordinates will be the center of the area where the event occurs.

Location field (deprecated)

Address data in the geo field

The geo field also contains address information (as of June 2024). The address subfield within the geo field can contain the following information:

  • country_code (required) - 2 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

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.

See below for an example of the address subfield within the geo field:

"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

Where an area event has a Point-type geometry, it means the event applies to the Geonames Place of the event.

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

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.

The geo field in the Events API response contains the longitude and latitude for point events. Below 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 ). See the example below:

For a point event, its location coordinates are where the event occurs. This may be the location of a venue. For example, a has a latitude and longitude of -122.38926979999997, 37.7785951, which corresponds to the address of Oracle Park, 24 Willie Mays Plaza.

Area events cover either a Geonames Place, for example , 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 for more information.

The location field was previously used for latitude and longitude information. The location field's value contains coordinates in order: [longitude, latitude]. Note the geo field is preferred over the location field as the location field will be deprecated in future.

For attended events when they are linked to a then the address information will correspond to the address of the venue.

The geo field contains geometry information about an event's location in 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.

The example event snippet is a . The GeoJSON data in the geo.geometry field can be plotted using tools that accept GeoJSON such as . All our events with a Polygon or MultiPolygon will display the geometry's shape when viewed in our or our . A plot of the flood warning event's geometry is shown below.

Below is an example of an ; 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 notebook.

geojson standard
San Francisco Giants MLB game at Oracle Park
GeoJSON
GeoJSON
flood warning in Missouri
geojson.io
WebApp
Public Event page
event with a MultiPolygon geometry
Severe-Weather Events Data Exploration
Thanksgiving Day
GeoJSON
venue entities
MLB game
Christmas Day in the United Kingdom
flood warning
venue entity
Raw polygon before simplification
Polygon after simplification