Visit website Control Center Try for Free

Get Features

The Features API provides features for ML Models across all types of demand causal factors, including attended events and non-attended events.

Request

HTTP Request

POST https://api.predicthq.com/v1/features/

Request Headers

HeaderValue

Content-Type

Receive results in JSON or CSV by specifying the appropriate Content-Type header.

Supported values:

  • application/json

  • text/csv

Request Body

FieldDescription

active object

The date range to calculate features for. This is named "active" because it includes events that are active within the date range. A multi-day event might start or end outside the specified date range - the days the event is active within the specified range will be included in the calculations.

Supports the following fields:

  • gt - greater than

  • gte - greater than or equal

  • lt - less than

  • lte - less than or equal

Note that all dates here are in local time (not UTC). Features API works on specific locations.

Please also note that the maximum supported date range is 90 days. If you require features over a wider date range please make multiple API requests.

E.g.

{
  "active": {
    "gte": "2019-11-28",
    "lte": "2019-11-29"
  }
}

hour_of_day_start object

Time range (per day) to calculate features for.

Note: This field is currently only supported on phq_viewership_* features.

If your location only operates within certain hours of the day you can use this filter to only include records that are happening within those hours.

Supports the following fields:

  • gt - greater than

  • gte - greater than or equal

  • lt - less than

  • lte - less than or equal

The values are hours between 0 and 23 (i.e. 24h format).

E.g. only include events happening between 1pm and 3pm each day.

{
  "hour_of_day_start": {
    "gte": 13,
    "lte": 15
  }
}

location object

Location to calculate features for. You can specify the location as a latitude/longitude (with radius), Place ID or Saved Location ID.

We recommend using a lat/lon+radius so your location can be more accurately defined, and we strongly recommend using our Suggested Radius API to work out a suitable radius around your location.

Note, when using Place IDs or Saved Location IDs a maximum of 3 IDs may be used.

E.g. using Place IDs.

{
  "location": {
    "place_id": [
      5224323,
      5811704,
      4887398
    ]
  }
}

E.g. using Saved Location IDs.

{
  "location": {
    "saved_location_id": [
      "BN7ZSw8xza9FviPVfyCycd",
      "X3uyTFbDOUaX2q_Qh5i31b",
      "X3uyTFbDOUhrfq_Qh5i31A"
    ]
  }
}

E.g. using a latitude/longitude and radius (recommended)

{
  "location": {
    "geo": {
      "lat": 41.75038,
      "lon": -71.49978,
      "radius": "2.6mi"
    }
  }
}

The radius is in the format: <radius><radius_unit>

Supported radius units are:

  • m - meters

  • km - kilometers

  • ft - feet

  • mi - miles

<feature_name> object or boolean

The name of the feature you're requesting. You can request multiple features in a single request. Features can be further configured here, or you can set the value as true to perform the default calculations for that feature. Please see the tables below for a list of all currently supported features and how they can be further configured.

E.g. requesting certain stats fields and filtering for records with a PHQ Rank over 50.

{
  "phq_attendance_sports": {
    "stats": ["count", "std_dev", "median"],
    "phq_rank": { 
      "gt": 50
    }
  }
}

E.g. requesting the default calculations for a feature.

{
  "phq_attendance_concerts": true
}

Available Features

PHQ Attendance features provide daily-level aggregated stats based on the number of people who we predict will attend events on a given day. This takes into account complications like distributing attendance across multi-day events.

FeatureDescription

phq_attendance_academic_graduation

Academic - Graduation

phq_attendance_academic_social

Academic - Social

phq_attendance_community

Community

phq_attendance_concerts

Concerts

phq_attendance_conferences

Conferences

phq_attendance_expos

Expos

phq_attendance_festivals

Festivals

phq_attendance_performing_arts

Performing Arts

phq_attendance_sports

Sports

phq_attendance_school_holidays

School Holidays

Impact Patterns

We have recently extended our research on impact patterns to surface the accommodation and hospitality vertical accross phq_attendance as the impact_type. This yields new features:

FeatureDescription

phq_attendance_community_accommodation

Community accommodation impact

phq_attendance_concerts_accommodation

Concerts accommodation impact

phq_attendance_conferences_accommodation

Conferences accommodation impact

phq_attendance_expos_accommodation

Expos accommodation impact

phq_attendance_festivals_accommodation

Festivals accommodation impact

phq_attendance_performing_arts_accommodation

Performing Arts accommodation impact

phq_attendance_sports_accommodation

Sports accommodation impact

phq_attendance_community_hospitality

Community hospitality impact

phq_attendance_concerts_hospitality

Concerts hospitality impact

phq_attendance_conferences_hospitality

Conferences hospitality impact

phq_attendance_expos_hospitality

Expos hospitality impact

phq_attendance_festivals_hospitality

Festivals hospitality impact

phq_attendance_performing_arts_hospitality

Performing Arts hospitality impact

phq_attendance_sports_hospitality

Sports hospitality impact

Configuration

You can configure PHQ Attendance features using the options below.

FieldDescription

stats object optional

You can optionally configure which fields are calculated for each of these features by providing the list of stats fields you would like.

Default fields are count and sum.

Supported fields are:

  • count

  • sum

  • min

  • max

  • avg

  • median

  • std_dev

E.g.

{
  "stats": [
    "count",
    "std_dev",
    "median"
  ]
}

phq_rank object optional

Filter for events with a PHQ Rank within a certain range.

Supports the following fields:

  • gt - greater than

  • gte - greater than or equal

  • lt - less than

  • lte - less than or equal

E.g. 

{
  "phq_rank": {
    "gt": 50,
    "lt": 80
  }
}

Response

Response Fields

FieldDescription

results array

List of results where each item is a Feature.

Please refer to the Feature Response Fields section below for the structure of each record. Note that pagination is not required in this API.

Feature Response Fields

Other than the date, the structure of each result here will depend on how you configured the feature in your request and the type of feature.

FieldDescription

date string

Date in local time. E.g. 2023-10-01

<phq_attendance_*> object

Daily-level feature result. The structure of the result here will depend on how you configured the feature in your request.

PHQ Attendance features are stats-based.

Default fields are count and sum.

E.g.

{
  "stats": {
    "count": 5,
    "sum": 17307,
    "min": 1000,
    "max": 9215,
    "avg": 3461.4,
    "median": 2620.0,
    "std_dev": 2978.810473997968
  }
}

Response Format

You can receive responses formatted as JSON (default) or CSV. Use the Content-Type header when performing your request to define which format you would like to receive.

With the Content-Type header set to application/json you will receive the results as JSON like the example below:

{
  "results": [
    {
      "date": "2019-11-16",
      "phq_attendance_concerts": {
        "stats": {
          "count": 20,
          "sum": 6751
        }
      },
      "phq_attendance_conferences": {
        "stats": {
          "min": 1500,
          "max": 1500
        }
      },
      "phq_attendance_sports": {
        "stats": {
          "count": 5,
          "sum": 17307,
          "min": 1000,
          "max": 9215,
          "avg": 3461.4,
          "median": 2620.0,
          "std_dev": 2978.810473997968
        }
      },
      "phq_rank_public_holidays": {
        "rank_levels": {
          "1": 0,
          "2": 0,
          "3": 0,
          "4": 0,
          "5": 0
        }
      }
    },
    {
      "date": "2019-11-17",
      "phq_attendance_concerts": {
        "stats": {
          "count": 2,
          "sum": 241
        }
      },
      "phq_attendance_conferences": {
        "stats": {
          "min": 67,
          "max": 67
        }
      },
      "phq_attendance_sports": {
        "stats": {
          "count": 1,
          "sum": 852,
          "min": 852,
          "max": 852,
          "avg": 852.0,
          "median": 852.0,
          "std_dev": 0.0
        }
      },
      "phq_rank_public_holidays": {
        "rank_levels": {
          "1": 0,
          "2": 0,
          "3": 0,
          "4": 0,
          "5": 0
        }
      }
    }
  ]
}

Examples

curl -X POST https://api.predicthq.com/v1/features/ \
     -H "Accept: application/json" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     --data @<(cat <<EOF
    {
        "active": {
            "gte": "2019-11-16",
            "lte": "2019-11-17"
        },
        "location": {
            "geo": {
                "lat": "37.78428",
                "lon": "-122.40075",
                "radius": "2.6mi"
            }
        },
        "phq_attendance_conferences": {
            "stats": [
                "min",
                "max"
            ]
        },
        "phq_attendance_sports": {
            "stats": ["count", "std_dev", "median"],
            "phq_rank": { 
                "gt": 50
            }    
        },
        "phq_attendance_concerts": true,
        "phq_rank_public_holidays": true
    }
    EOF
    )

Guides

Below are some guides relevant to this API:

PreviousFeaturesNextBeam

Last updated

PredictHQ

Terms of ServicePrivacy PolicyGitHub

© 2024 PredictHQ Ltd