Data Aggregations
Overview
Hyperia stores and indexes analyzed meetings and uploaded media files in a searchable online index. APIs are provided for performing aggregation operations such as retrieving the top-mentioned topics, intent/action tags, or top speakers from a set of analyzed recordings. Filtering options are provided to restrict the recordings used during rank analysis. For instance, you can request the "top speakers from calls within a specific datetime range", or the "top topics from recordings whose titles mention a specific keyword".
Retrieve Top Speakers
Retrieves an aggregation of the top speakers for conversations in a workspace. An optional filter payload may be provided which enables this aggregation to be filtered at the document-level (for instance, to retrieve all speakers from documents matching a title or date-time filter).
Endpoint:
/v1/workspace/id/<workspace_id>/doc/ranked/speaker
HTTP Method:
PUT
URI Parameters:
| Name | Description |
|---|---|
| workspace_id | ID of the workspace to retrieve top speakers from |
PUT JSON Payload Parameters:
Supported search filters are described here.
Returns:
If successful: HTTP 200
Return Payload:
{
"status": "ok",
"speakers": [
{
"id": "GUID_OF_SPEAKER",
"count": "OCCURRENCE_COUNT_OF_SPEAKER",
"name": "NAME_OF_SPEAKER"
}
]
}Code Sample:
from hyperia import Hyperia
import sys
workspace_id = "SOME_WORKSPACE_ID"
hyperia = Hyperia()
// optional filter
filters['title_phrase_match'] = "SOME_TITLE_FILTER"
response = hyperia.workspace_ranked_speakers(workspace_id, filter_params=filters)
if not response:
sys.exit(-1)
speakers = response['speakers']
for speaker in speakers:
print(f"{speaker['name']}: {speaker['count']} occurrences")Retrieve Top Topics
Retrieves an aggregation of the top topics from conversations in a workspace. An optional filter payload may be provided which enables this aggregation to be filtered at the document-level (for instance, to retrieve all topics from documents matching a title or date-time filter).
Endpoint:
/v1/workspace/id/<workspace_id>/doc/ranked/topic
HTTP Method:
PUT
URI Parameters:
| Name | Description |
|---|---|
| workspace_id | ID of the workspace to retrieve top topics from |
PUT JSON Payload Parameters:
Supported search filters are described here.
Returns:
If successful: HTTP 200
Return Payload:
{
"status": "ok",
"topics": [
{
"text": "NAME_OF_TOPIC",
"count": "OCCURRENCE_COUNT_OF_TOPIC"
}
]
}Code Sample:
from hyperia import Hyperia
import sys
workspace_id = "SOME_WORKSPACE_ID"
hyperia = Hyperia()
// optional filter
filters['title_phrase_match'] = "SOME_TITLE_FILTER"
response = hyperia.workspace_ranked_topics(workspace_id, filter_params=filters)
if not response:
sys.exit(-1)
topics = response['topics']
for topic in topics:
print(f"{topic['text']}: {topic['count']} occurrences")Retrieve Top Tags
Retrieves an aggregation of the top tags from conversations in a workspace. An optional filter payload may be provided which enables this aggregation to be filtered at the document-level (for instance, to retrieve all tags from documents matching a title or date-time filter).
Endpoint:
/v1/workspace/id/<workspace_id>/doc/ranked/tag
HTTP Method:
PUT
URI Parameters:
| Name | Description |
|---|---|
| workspace_id | ID of the workspace to retrieve top tags from |
PUT JSON Payload Parameters:
Supported search filters are described here.
Returns:
If successful: HTTP 200
Return Payload:
{
"status": "ok",
"tags": [
{
"text": "NAME_OF_TAG",
"count": "OCCURRENCE_COUNT_OF_TAG"
}
]
}Code Sample:
from hyperia import Hyperia
import sys
workspace_id = "SOME_WORKSPACE_ID"
hyperia = Hyperia()
// optional filter
filters['title_phrase_match'] = "SOME_TITLE_FILTER"
response = hyperia.workspace_ranked_tags(workspace_id, filter_params=filters)
if not response:
sys.exit(-1)
tags = response['tags']
for tag in tags:
print(f"{tag['text']}: {tag['count']} occurrences")Supported Search Filters
Hyperia aggregation APIs support filtering the documents that are considered when performing the aggregation request using a variety of search and constraint filters. Listed below are all currently supported document-level search and constraint filters:
Document-level Conversation Metadata:
| Name | Description |
|---|---|
| title_phrase_match_list | Array of strings, where each string is a unigram or multigram (phrase) search. |
| description_phrase_match_list | Array of strings, where each string is a unigram or multigram (phrase) search. |
| speaker_list | Array of speaker IDs. Results will be restricted to documents containing at least one of the specified speaker IDs. |
| topic_list | Array of topics to match against. Array is applied as an OR query (only one topic in the array must match) |
Date-time Metadata:
| Name | Description |
|---|---|
| date_range | Date constraint object. Contains: "time_zone": "+01:00", "gte": "YYYY-MM-DD", "lte": "YYYY-MM-DD" |
| time_range | Time constraint object. Contains: "time_zone": "+01:00", "gte": "HH:MM:SS-0600", "lte": "HH:MM:SS-0600" |
Custom Labels and Tags Metadata:
| Name | Description |
|---|---|
| label_id_list | Array of label IDs. Results will be restricted to documents containing at least one of the specified labels. |
| tag_id_list | Array of tag IDs. Results will be restricted to documents containing at least one of the specified tags. |