Get ML Features

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.

E.g.

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

An optional beam analysis object which if provided will calculate the location, interval, week_start_day, and phq_* feature selection (including per-feature stats and rank filters) from the Beam analysis (and optionally its group).

Fields:

• analysis_id (required if beam is present): Beam analysis ID
• group_id (optional): Beam analysis group ID

If beam.analysis_id is provided, the location, interval, week_start_day, and phq_* feature selection (including per-feature stats and rank filters) will be calculated from the Beam analysis.

The following fields are mutually exclusive with beam and cannot be included in the same request:

• location
• interval
• All phq_attendance_* features
• All phq_rank_* features
• All phq_impact_* features
• All phq_viewership_* features
• All phq_spend_* features

Including any of the above when beam is present will result in a validation error.

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

Time range (per day) to calculate features for, based on the hours during which events are active.

Supported on phq_attendance_*, phq_impact_*, phq_spend_*, and phq_viewership_* features. Not applicable to phq_rank_* features.

If your location only operates within certain hours of the day you can use this filter to only include events that are active during those hours. An event is considered active during an hour if it has started before or during that hour and ends during or after that hour.

Note: Only one of hour_of_day_active, hour_of_day_start, or hour_of_day_end may be specified per request.

Supports the following fields:

• gt - greater than
• gte - greater than or equal
• lt - less than
• lte - less than or equal

The values are hours in 24h format. Valid values are 0-23 for gte/lte; for exclusive operators, gt must be less than 23 and lt must be greater than 0.

E.g. only include events active between 9am and 5pm each day.

E.g.

{
  "hour_of_day_active": {
    "gte": 9,
    "lte": 17
  }
}

Time range (per day) to calculate features for, based on event start hour.

Supported on phq_attendance_*, phq_impact_*, phq_spend_*, and phq_viewership_* features. Not applicable to phq_rank_* features.

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

Note: Only one of hour_of_day_active, hour_of_day_start, or hour_of_day_end may be specified per request.

Supports the following fields:

• gt - greater than
• gte - greater than or equal
• lt - less than
• lte - less than or equal

The values are hours in 24h format. Valid values are 0-23 for gte/lte; for exclusive operators, gt must be less than 23 and lt must be greater than 0.

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

E.g.

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

Time range (per day) to calculate features for, based on event end hour.

Supported on phq_attendance_*, phq_impact_*, phq_spend_*, and phq_viewership_* features. Not applicable to phq_rank_* features.

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

Note: Only one of hour_of_day_active, hour_of_day_start, or hour_of_day_end may be specified per request.

Supports the following fields:

• gt - greater than
• gte - greater than or equal
• lt - less than
• lte - less than or equal

The values are hours in 24h format. Valid values are 0-23 for gte/lte; for exclusive operators, gt must be less than 23 and lt must be greater than 0.

E.g. only include events ending between 5pm and 9pm each day.

E.g.

{
  "hour_of_day_end": {
    "gte": 17,
    "lte": 21
  }
}

Location to calculate features for. Must not be specified when beam.analysis_id is provided — the location is derived from the Beam analysis and the request will be rejected if both are included.

You can specify the location as a latitude/longitude (with radius), Place ID(s) or Saved Location IDs.

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:

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

Include or Exclude predicted events.