Table of contents

Histogram API

The histogram API returns the frequency of occurrences for a particular search term within given time intervals.

Request

To get histogram data for an item by its ID, make the following request:

GET /api/data/segments/{id}/histogram
  • {id} - (string) Required. The item id for the histogram you are requesting. Item must be of video file type.
  • {.field=value} - (string) Required. At least a single field-value pair to specify the search term and value you’re creating a histogram. All field-value pairs are preceded by a dot (.) to denote it as a search field and multiple pairs are separated by an ampersand character (&).
  • {page} - (integer) Optional. Index of total pages containing results (Default: 0).
  • {interval} - (integer) Optional. Interval in seconds (Default: 5).

Response

Each successful histogram API response contains the results of the API call, plus some additional useful information. Here’s a sample response:

{
    "limit": 20,
    "page": 0,
    "total_hits": 25,
    "results": [
        {
            "start_at": 10,
            "end_at": 15,
            "count": 8
        },
        {
            "start_at": 25,
            "end_at": 30,
            "count": 5
        },
        {
            "start_at": 35,
            "end_at": 40,
            "count": 7
        }
    ],
    "itemID": "1234",
    "totalPages": 2,
    "parameters": [
        {
            "field": "{field}",
            "value": "{value}"
        }
    ],
    "nextPage": 1
}
  • limit - (integer) The limited number of results per page.
  • page - (integer) Index of page for current results.
  • total_hits - (integer) The number of total results found. If 0 no occurrences were found.
  • results - (array) An array holding each interval where occurrences are found.
  • start_at - (integer) Start time in seconds and multiple of interval.
  • end_at - (integer) End time in seconds and multiple of interval.
  • count - (integer) Number of occurrences found between start_at and end_at.
  • item_id - (string) The item id for the histogram you requested.
  • total_pages - (integer) The number of pages results fit in.
  • parameters - (array) Array holding field-value pairs used to retrieve histogram.
  • field - (string) Search field used to retrieve histogram.
  • value - (string) Value assigned to search field.
  • next_page - (integer) Index of next page. Omitted if last page.

Example

Below is a GET to retrieve a histogram of occurrences for actress Tiwa Savage in a particular video. The item ID is 07fdc94375ddf05aba7133f9f82f5742 and interval is set to 10.

GET /api/data/segments/07fdc94375ddf05aba7133f9f82f5742/histogram?interval=10&.video_vision.categories.detail.celebrities.name.raw=Tiwa Savage

Tiwa Savage is found once between seconds 10 and 20 of the video. The response appears in the format below:

{
    "limit": 20,
    "page": 0,
    "total_hits": 1,
    "results": [
        {
            "start_at": 10,
            "end_at": 20,
            "count": 1
        }
    ],
    "itemID": "07fdc94375ddf05aba7133f9f82f5742",
    "totalPages": 1,
    "parameters": [
        {
            "field": "video_vision.categories.detail.celebrities.name.raw",
            "value": "Tiwa Savage"
        }
    ]
}

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.