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

Query Parameters

Parameter

Description

Request Body

Field

Description

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.

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.

Configuration

You can configure PHQ Attendance features using the options below.

PHQ Rank features provide the daily-level aggregated sum of events bucketed by PHQ Rank level (1-5).

PHQ Rank Impact Pattern Features

See the "Holidays and Observances Impact Pattern Features" under PHQ Impact in the tab above. These features cover the Accommodation, Retail, and Hospitality (Food & Beverage) industries.

We recommend that if you operate in the supported industries you use the demand impact features for holidays and observances instead of the generic features as these will result in greater forecast accuracy as they include the impact before an event starts and after it finishes.

PHQ Rank Generic Features

These are generic features that do not include demand impact patterns and should be used if you are not in one of the industries that we have impact patterns for.

Configuration

PHQ Rank features cannot currently be configured further. When requesting phq_rank_* features set the value as true indicating you require the default calculations.

Response

Response Fields

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.

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

With the Accept header set to text/csv you will receive the results as CSV like the example below:

date,phq_attendance_concerts_stats_count,phq_attendance_concerts_stats_sum,phq_attendance_conferences_stats_min,phq_attendance_conferences_stats_max,phq_attendance_sports_stats_count,phq_attendance_sports_stats_sum,phq_attendance_sports_stats_min,phq_attendance_sports_stats_max,phq_attendance_sports_stats_avg,phq_attendance_sports_stats_median,phq_attendance_sports_stats_std_dev,phq_rank_public_holidays_rank_levels_1,phq_rank_public_holidays_rank_levels_2,phq_rank_public_holidays_rank_levels_3,phq_rank_public_holidays_rank_levels_4,phq_rank_public_holidays_rank_levels_5
2019-11-16,43,24546,11,1000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-17,25,13440,11,146,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-18,6,2021,11,700,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-19,10,6047,11,171000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-20,14,59704,11,171000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-21,21,60851,11,171000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-22,35,25760,11,171000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-23,29,25425,11,394,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-24,18,23410,11,500,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-25,6,5122,11,1000,1,18064,18064,18064,18064.0,18064.0,0.0,0,0,0,0,0
2019-11-26,8,6861,11,1000,0,0,0,0,0.0,0.0,,0,0,0,0,0
2019-11-27,12,6225,11,500,1,18064,18064,18064,18064.0,18064.0,0.0,0,0,0,0,0

The same data represented as a table:

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
    )

import requests

data = {
    "active": {
        "gte": "2019-11-16",
        "lte": "2019-11-27"
    },
    "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
}

response = requests.post(
    url="https://api.predicthq.com/v1/features/",
    headers={
      "Authorization": "Bearer $ACCESS_TOKEN",
      "Accept": "application/json"
    },
    params={
      "offset": 0,
      "limit": 100
    },
    json=data
)

print(response.json())

from predicthq import Client

phq = Client(access_token="$ACCESS_TOKEN")

for feature in phq.features.obtain_features(
        active__gte="2019-11-16",
        active__lte="2019-11-27",
        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_attendance_sports__phq_rank={
            "gt": 50
        },
        phq_attendance_concerts=True,
        phq_rank_public_holidays=True
):
    print(feature.date, feature.phq_attendance_conferences.stats.min, 
        feature.phq_attendance_conferences.stats.max,
        feature.phq_attendance_sports.stats.count,
        feature.phq_attendance_sports.stats.std_dev,
        feature.phq_attendance_sports.stats.median,
        feature.phq_attendance_concerts.stats.count,
        feature.phq_attendance_concerts.stats.sum,
        feature.phq_rank_public_holidays.rank_levels)

Guides

Below are some guides relevant to this API:

PreviousFeatures NextBeam

Last updated 3 days ago