For the latest source, discussions, bug reports, etc., please visit the GitHub repository

PredictHQ API Client for Python

PredictHQ is the demand intelligence company combining real-world events into one global source of truth to help businesses better understand demand and plan for the future.

Installation

The PredictHQ Python client is distributed as a pip package. You can simply install it by running

pip install predicthq

Migrating from version <= 2.4.0

If you are migrating to version 3.0.0 or above from an earlier version, please check the V3 breaking changes details.

If you are migrating to version 4.0.0 or above from an earlier version, please check the V4 breaking changes details.

If you are migrating to version 5.0.0 or above from an earlier version, please check the V5 breaking changes details.

Usage

We support the following endpoints available in our API.

• broadcasts
• events
• features
• impact_area
• places
• radius
• beam
• saved_locations

Please refer to our API Documentation for a description of each endpoint.

The usecases/ folder is a good starting point to get familiar with the Python SDK. You can also review the tests/ for a kitchen sink of all the parameters available per endpoint.

Pagination

Additional examples are available in usecases/pagination.py file.

By default the search() method only returns the first page of results, with a default page size of 10.

from predicthq import Client

phq = Client(access_token="abc123")


for event in phq.events.search():
    print(event.rank, event.category, event.title, event.start.strftime("%Y-%m-%d"))

You can chain the iter_all() generator to iterate over all your events.

for event in phq.events.search().iter_all():
    print(event.rank, event.category, event.title, event.start.strftime("%Y-%m-%d"))

Events endpoint

Additional examples are available in usecases/events folder.

The following example searches for the Katy Perry events (full text search) with rank level of 4 or 5 (rank >= 60) in the concerts category.

from predicthq import Client

phq = Client(access_token="abc123")


for event in phq.events.search(q="Katy Perry", rank_level=[4, 5], category="concerts"):
    print(event.rank, event.category, event.title, event.start.strftime("%Y-%m-%d"))

Please refer to our Events endpoint documentation for the lists of search parameters and event fields available.

Broadcasts endpoint

Additional examples are available in usecases/broadcasts folder.

The following example searches for the broadcasts with PHQ viewership gte 100 and with event (the physical event the broadcast links to) label nfl.

from predicthq import Client

phq = Client(access_token="abc123")


for broadcast in phq.broadcasts.search(phq_viewership__gte=100, event__label="nfl"):
    print(broadcast.event.title, broadcast.phq_viewership, broadcast.event.labels, broadcast.dates.start.strftime("%Y-%m-%d"))

Please refer to our Broadcasts endpoint documentation for the lists of search parameters and broadcast fields available.

Places endpoint

Additional examples are available in usecases/places.py file.

The following example searches for the New York places (full text search) in the US.

from predicthq import Client

phq = Client(access_token="abc123")


for place in phq.places.search(q="New York", country="US"):
    print(place.id, place.name, place.type, place.location)

Please refer to our Places endpoint documentation for the lists of search parameters and place fields available.

Features endpoint

Note: If you're trying to retrieve over 90 days worth of features, you will need to paginate through all pages using .iter_all() as outlined in usecases/pagination.py.

The following example obtain features of events which are active between 2017-12-31 and 2018-01-02, with place_id 4671654.

Requested features:

• rank_levels for public_holidays
• count and median of sporting events which has a phq_rank greater than 50

By place_id list (e.g. Austin):

from predicthq import Client

phq = Client(access_token="abc123")


for feature in phq.features.obtain_features(
        active__gte="2017-12-31",
        active__lte="2018-01-02",
        location__place_id=["4671654"],
        phq_rank_public_holidays=True,
        phq_attendance_sports__stats=["count", "median"],
        phq_attendance_sports__phq_rank={
            "gt": 50
        }
):
    print(feature.date, feature.phq_attendance_sports.stats.count, feature.phq_rank_public_holidays.rank_levels)

by geo:

from predicthq import Client

phq = Client(access_token="abc123")


for feature in phq.features.obtain_features(
        active__gte="2017-12-31",
        active__lte="2018-01-02",
        location__geo={
            "lon": -97.74306,
            "lat": 30.26715,
            "radius": "150km"
        },
        phq_rank_public_holidays=True,
        phq_attendance_sports__stats=["count", "median"],
        phq_attendance_sports__phq_rank={
            "gt": 50
        }
):
    print(feature.date, feature.phq_attendance_sports.stats.count, feature.phq_rank_public_holidays.rank_levels)

The following example obtains features of broadcasts which are active between 2017-12-31 and 2018-01-02, with place_id 4671654

Requested features:

• count and median of broadcasts which start between 9am - 11am and have a phq_rank greater than 50

from predicthq import Client

phq = Client(access_token="abc123")


for feature in phq.features.obtain_features(
        active__gte="2017-12-31",
        active__lte="2018-01-02",
        hour_of_day_start__gt=9,
        hour_of_day_start__lte=11,
        location__place_id=["4671654"],
        phq_viewership_sports_american_football__stats=["count", "median"],
        phq_viewership_sports_american_football__phq_rank={
            "gt": 50
        }
):
    print(feature.date, feature.phq_viewership_sports_american_football.stats.count, feature.phq_viewership_sports_american_football.stats.median)

Please refer to our Features endpoint documentation for the lists of supported features and response fields available.

Predicted Impact Area endpoint

Predicted Impact Area is the successor to the Suggested Radius API. It provides a more accurate representation of event impact than a radius-based approach.

Additional examples are available in usecases/impact_area.py file.

The following example obtains the impact area as a polygon for a given location and industry.

from predicthq import Client

phq = Client(access_token="abc123")


result = phq.impact_area.search(location__origin="45.5051,-122.6750", industry="accommodation")
print(result.geojson.geometry.type, result.geojson.geometry.coordinates)
print(result.location.model_dump(exclude_none=True))

You can also get the impact area as a radius instead of a polygon.

from predicthq import Client

phq = Client(access_token="abc123")


result = phq.impact_area.search(location__origin="45.5051,-122.6750", industry="retail", area_type="radius", radius_unit="km")
print(result.geojson.properties.radius, result.geojson.properties.radius_unit)
print(result.geojson.geometry.coordinates)

Please refer to our Predicted Impact Area endpoint documentation for the lists of search parameters and response fields available.

Suggested Radius endpoint

Predicted Impact Area is the successor to this API, providing a more accurate representation of event impact than a radius. Suggested Radius remains available and existing implementations are unaffected.

The following example obtain suggested radius to be used when retrieving events for location {"lat": 45.5051, "lon": -122.6750} and generic industry.

Additional examples are available in usecases/radius folder.

from predicthq import Client

phq = Client(access_token="abc123")


suggested_radius = phq.radius.search(location__origin="45.5051,-122.6750")
print(suggested_radius.radius, suggested_radius.radius_unit, suggested_radius.location.model_dump(exclude_none=True))

Beam endpoints

Get Analysis.

Additional examples are available in usecases/beam/analysis folder.

from predicthq import Client

phq = Client(access_token="abc123")


analysis = phq.beam.analysis.get(analysis_id="abc123")
print(analysis.model_dump(exclude_none=True))

Get Analysis Group.

Additional examples are available in usecases/beam/analysis_group folder.

from predicthq import Client

phq = Client(access_token="abc123")


analysis_group = phq.beam.analysis_group.get(group_id="abc123")
print(analysis_group.model_dump(exlcude_none=True))

Saved Locations endpoints

Additional examples are available in usecases/saved_locations.py file.

The following example searches for the saved_locations according to the parameters defined:

from predicthq import Client

phq = Client(access_token="abc123")


for saved_location in phq.saved_locations.search(
        labels=["test", "retail"],
        q="London", 
        sort="-created",
    ):
        print(saved_location.location_id, saved_location.create_dt, saved_location.status)

Serializing search results into a dictionary

All search results can be serialized into a dictionary using the .model_dump() method call.

To keep None values use .model_dump()

To remove None values use .model_dump(exclude_none=True)

Examples:

from predicthq import Client

phq = Client(access_token="abc123")


for event in phq.events.search(q="Katy Perry", rank_level=[4, 5], category="concerts"):
    # Serialize event data into a dictionary and remove None values
    print(event.model_dump(exclude_none=True))

from predicthq import Client

phq = Client(access_token="abc123")


for feature in phq.features.obtain_features(
        active__gte="2024-12-31",
        active__lte="2025-01-02",
        location__place_id=["4671654"],
        phq_rank_public_holidays=True,
        phq_attendance_sports__stats=["count", "median"],
        phq_attendance_sports__phq_rank={
            "gt": 50
        }
):
    # Serialize feature data into a dictionary and remove None values
    print(feature.model_dump(exclude_none=True))

Config parameters

We support some config parameters for additional flexibility.

Supported config parameters:

• verify_ssl

from predicthq import Client

phq = Client(access_token="abc123")


# double underscore syntax
for event in phq.events.search(config__verify_ssl=False):
    print(event.rank, event.category, event.title, event.start.strftime("%Y-%m-%d"))

# dictionary syntax
for event in phq.events.search(config={"verify_ssl": False}):
    print(event.rank, event.category, event.title, event.start.strftime("%Y-%m-%d"))

Running Tests

pip install tox
tox

Found a Bug?

Please log an issue.