Visit websiteControl CenterTry 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

Header
Value

Accept

Receive results in JSON or CSV by specifying the appropriate Accept header.

Supported values:

  • application/json

  • text/csv

Query Parameters

Parameter
Description

offset number

The number of results to skip. The default is 0.

E.g. ?offset=20

limit number

The maximum number of results to return per page.

The default limit is 100 and the maximum per page is 100.

E.g. ?limit=10

Request Body

Field
Description

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

beam object

An optional beam analysis object which if provided will calculate the location, interval, week_start_day , phq_* features including stats and phq_rank from the Beam analysis and optionally the Beam analysis group.

Supports the following fields:

  • analysis_id - Beam analysis id (Required if beam block is present in the request body)

  • group_id - Beam analysis group id (Optional)

If beam.analysis_id is provided, the location, interval, week_start_day , phq_* features includingstats and phq_rank will be calculated from the Beam analysis.

E.g.

{
  "beam": {
    "analysis_id": "0SXAmHsoZo0"
  }
}

If both beam.analysis_id and beam.group_id are provided, all the above fields will be calculated from the Beam analysis but the phq_* features will be calculated from the Beam analysis Group.

Note: This is useful for when you want to request features for a variety of locations while maintaining feature consistency by limiting the returned features to those of the group's feature importance results.

E.g.

{
  "beam": {
    "analysis_id": "0SXaMHsoYo0",
    "group_id": "QxE9BcLq7ZY"
  }
}

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(s) or Saved Location ID(s).

We recommend using a lat/lon+radius or a saved location id (for a point and radius location) as they could define the location of your interest more accurately. To work out a suitable radius around your location we strongly recommend using our Suggested Radius API.

Note: When using Place IDs or Saved Location IDs a maximum of 3 IDs may be used.

Note: When using lat/lon+radius, the radius must be in the format <radius><radius_unit>, where <radius> is an integer or a float number up to 2 decimal places and <radius_unit> is one of:

  • m - meters

  • km - kilometers

  • ft - feet

  • mi - miles

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.62mi"
    }
  }
}

interval string optional

Aggregation interval. Possible values:

  • day (default) for daily aggregation

  • week for weekly aggregation

week_start_day string optional

The weekday to be treated as the start of the week.

Possible values:

  • monday (default)

  • tuesday

  • wednesday

  • thursday

  • friday

  • saturday

  • sunday

Only applicable when interval is set to week.

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

We recommend using impact pattern features instead of generic features if you are in one of the supported industries. See #attended-events-impact-patterns.

Attended Events Generic Features

Use the generic features in this table if you are not in one of the industries covered by the impact pattern features listed below.

Feature
Description

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

Attended Events Impact Pattern Features

Demand impact patterns model the impact of leading days (days before the event), lagging days (days after an event), and the days the event occurs. In the Features API, Impact Patterns are provided as different features with a feature per industry. We have impact pattern features for the accommodation, hospitality (which covers food & beverage including restaurants), and retail industries.

The features above are generic features and the features in the table below are the impact pattern features per industry. For example, if you were in the accommodation industry and wanted a feature for the conferences category you'd use phq_attendance_conferences_accommodation.

We recommend using impact pattern features instead of generic features if you are in one of the supported industries. See Impact Patterns for more details.

Feature
Description

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

phq_attendance_community_retail

Community Retail impact

phq_attendance_concerts_retail

Concerts Retail impact

phq_attendance_conferences_retail

Conferences Retail impact

phq_attendance_expos_retail

Expos Retail impact

phq_attendance_festivals_retail

Festivals Retail impact

phq_attendance_performing_arts_retail

Performing Arts Retail impact

phq_attendance_sports_retail

Sports Retail impact

Configuration

You can configure PHQ Attendance features using the options below.

Field
Description

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

local_rank object optional

Filter for events with a Local 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.

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

Response

Response Fields

Field
Description

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.

Field
Description

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 Accept header when performing your request to define which format you would like to receive.

With the Accept 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/?offset=0&limit=100" \
     -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