Retrieve Aggregated Data of a Specific Segment via REST API

In some cases, users might wish to investigate their data and get all the relevant aggregated data of a specific segment, for example, the distribution of a metric in this segment in a specific time range.

For this, users can now leverage Mona's /get_segment REST API endpoint to retrieve said segment.

To access Mona's API, first, an accessToken must be generated and added to the request.

Once users have their accessToken they can add it to their authorization and send a POST request with the following mandatory params:

  • "contextClass"- The context class of the desired segment.
  • "timestampFrom" - the start time in epoch timestamp.
  • "timestampTo" - the end time in epoch timestamp.

Optional args:

  • "timeSeriesResolutions" - Allows you to get a time-series with values of the metric. Expected format is an array of TimeResolutions.
  • "withHistogram" - Default is False. Setting true will add the distribution histogram of the chosen metric to the response.
  • "timeZone" - The desired time zone.
  • "metrics" - The metric to get values of in the segment. Expected format is:
"metrics": [
  {
    "field": "feature_1",
    "types": [
      "average"
    ]
  }
]

Possible values for "types" are: average, sum, variance, normalized_variance, std, standard_error, interquartile range, and existence ratio.
If no ״metrics״ param is stated, the call will return the first field in the config.

Optional args for segments:

  • "excludedSegments" - Segments users wish to exclude from the desired segment. Expected format is SegmentsListType
  • "requestedSegments" - The requested segments. If none is stated, response will be "all data". Expected format is SegmentsListType
  • "baselineSegment" - The baseline of the requested segment. If none is stated, baseline will be "all data". Expected format is SegmentsType

In the following example, we are looking for the segment "occupation": "retail" in a 7 days time range with the average of "feature_1" as our metric, a time resolution of 1 day, and with a histogram.

curl --location --request POST 'https://api{YOUR-USER-ID}.monalabs.io/get_segment' \
--header 'Authorization: Bearer YOUR-ACCESS-TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "contextClass": "LOAN_APPLICATION_TUTORIAL",
  "timestampTo": 1619654399,
  "timestampFrom": 1619049600,
  "requestedSegments": [
    {
      "occupation": [
        {
          "value": "retail"
        }
      ]
    }
  ],
  "excludedSegments": [
    {
      "city": [
        {
          "value": "Arizona_Mesa"
        }
      ]
    }
  ],
  "metrics": [
    {
      "field": "feature_1",
      "types": [
        "average"
      ]
    }
  ],
  "timeSeriesResolutions": [
    "1d"
  ],
  "withHistogram": true
}'
import requests
url = "https://api{YOUR-USER-ID}.monalabs.io/get_segment"

payload={
  "contextClass": "LOAN_APPLICATION_TUTORIAL",
  "timestampTo": 1619654399,
  "timestampFrom": 1619049600,
  "requestedSegments": [
    {
      "occupation": [
        {
          "value": "retail"
        }
      ]
    }
  ],
  "negativeSegments": [
    {
      "city": [
        {
          "value": "Arizona_Mesa"
        }
      ]
    }
  ],
  "metrics": [
    {
      "metricName": "feature_1",
      "metricTypes": [
        "average"
      ]
    }
  ],
  "timeSeriesResolutions": [
    "1d"
  ],
  "withHistogram": true
}

headers = {
  'Authorization': 'Bearer YOUR-ACCESS-TOKEN',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)
from mona_sdk.client import Client

api_key = <YOUR-API-KEY>
secret = <YOUR-SECRET>

my_mona_client = Client(api_key, secret)

my_mona_client.get_aggregated_data_of_a_specific_segment(
    context_class="LOAN_APPLICATION_TUTORIAL",
    timestamp_to=1619654399,
    timestamp_from=1619049600,
    requested_segments=[{"occupation": [{"value": "retail"}]}],
    excluded_segments=[{"city": [{"value": "Arizona_Mesa"}]}],
    metrics=[{"field": "feature_1", "types": ["average"]}],
    time_series_resolutions="1d",
    with_histogram=True,
)

The response will be aggregated info of given metrics in the baseline and the requested segments, and the distribution histogram of the metric in both.

{
    "response_data": {
        "{}": {
            "amount": 2579,
            "ratio": 1,
            "fields": {
                "feature_1": {
                    "field_config": {
                        "visible_name": "feature_1",
                        "field_name": "feature_1",
                        "field_type": "numeric",
                        "min_threshold": 0.0,
                        "max_threshold": 819.943,
                        "interval": 16.39886,
                        "metrics": [
                            "average"
                        ],
                        "percents": []
                    },
                    "average": 1.9827396218959616,
                    "sum": 5113,
                    "variance": 120.94344574365675,
                    "normalized_variance": 60.99814842455542,
                    "std": 10.997429051540035,
                    "standard_error": 0.2165536448431773,
                    "min": 0.0,
                    "max": 511.9643249511719,
                    "time_series_1d": {
                        "1619049600000": {
                            "amount": 372,
                            "ratio": 1,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.8349670539697713,
                            "sum": 682,
                            "variance": 21.77625345390034,
                            "normalized_variance": 11.867381164577068,
                            "std": 4.666503343393246,
                            "standard_error": 0.2419469275198411,
                            "min": 0.005984037648886442,
                            "max": 62.26668930053711
                        },
                        "1619136000000": {
                            "amount": 387,
                            "ratio": 1,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 2.119406214161976,
                            "sum": 820,
                            "variance": 28.09755397685753,
                            "normalized_variance": 13.257276396147327,
                            "std": 5.300712591421792,
                            "standard_error": 0.26945036397861977,
                            "min": 0.016407251358032227,
                            "max": 52.86306381225586
                        },
                        "1619222400000": {
                            "amount": 524,
                            "ratio": 1,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.4575302535561376,
                            "sum": 763,
                            "variance": 10.734341173083779,
                            "normalized_variance": 7.364746732970877,
                            "std": 3.276330443206817,
                            "standard_error": 0.14312715995959263,
                            "min": 0.0,
                            "max": 52.82486343383789
                        },
                        "1619308800000": {
                            "amount": 299,
                            "ratio": 1,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.3884139638830189,
                            "sum": 415,
                            "variance": 9.272391468157307,
                            "normalized_variance": 6.678405511152404,
                            "std": 3.0450601748007062,
                            "standard_error": 0.1761003767822978,
                            "min": 0.0,
                            "max": 48.74291229248047
                        },
                        "1619395200000": {
                            "amount": 238,
                            "ratio": 1,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 2.2817749975546566,
                            "sum": 543,
                            "variance": 55.70004296545661,
                            "normalized_variance": 24.410839379496004,
                            "std": 7.463246141288428,
                            "standard_error": 0.4837703938569482,
                            "min": 0.0,
                            "max": 79.43721771240234
                        },
                        "1619481600000": {
                            "amount": 371,
                            "ratio": 1,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.5853041838954964,
                            "sum": 588,
                            "variance": 6.159730160695364,
                            "normalized_variance": 3.885519399538414,
                            "std": 2.481880367925772,
                            "standard_error": 0.12885280848799366,
                            "min": 0.0,
                            "max": 32.141693115234375
                        },
                        "1619568000000": {
                            "amount": 388,
                            "ratio": 1,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 3.351998985063323,
                            "sum": 1300,
                            "variance": 690.5326681304468,
                            "normalized_variance": 206.00622828571707,
                            "std": 26.277988281648327,
                            "standard_error": 1.3340627314598905,
                            "min": 0.06280815601348877,
                            "max": 511.9643249511719
                        }
                    },
                    "histogram": {
                        "0.0": 2548,
                        "16.39886": 13,
                        "32.79772": 12,
                        "49.19658": 3,
                        "65.59544": 2,
                        "81.9943": 0,
                        "98.39316": 0,
                        "114.79202": 0,
                        "131.19088": 0,
                        "147.58974": 0,
                        "163.9886": 0,
                        "180.38745999999998": 0,
                        "196.78632": 0,
                        "213.18518": 0,
                        "229.58404": 0,
                        "245.98289999999997": 0,
                        "262.38176": 0,
                        "278.78062": 0,
                        "295.17948": 0,
                        "311.57833999999997": 0,
                        "327.9772": 0,
                        "344.37606": 0,
                        "360.77491999999995": 0,
                        "377.17377999999997": 0,
                        "393.57264": 0,
                        "409.9715": 0,
                        "426.37036": 0,
                        "442.76921999999996": 0,
                        "459.16808": 0,
                        "475.56694": 0,
                        "491.96579999999994": 0,
                        "508.36465999999996": 1,
                        "524.76352": 0,
                        "541.16238": 0,
                        "557.56124": 0,
                        "573.9601": 0,
                        "590.35896": 0,
                        "606.7578199999999": 0,
                        "623.1566799999999": 0,
                        "639.55554": 0,
                        "655.9544": 0,
                        "672.35326": 0,
                        "688.75212": 0,
                        "705.15098": 0,
                        "721.5498399999999": 0,
                        "737.9486999999999": 0,
                        "754.3475599999999": 0,
                        "770.74642": 0,
                        "787.14528": 0,
                        "803.54414": 0,
                        "819.943": 0
                    }
                }
            },
            "sampling_factor": 1,
            "failed_shards_factor": 1.0
        },
        "{\"occupation\": [{\"value\": \"retail\"}]}": {
            "amount": 418,
            "ratio": 0.16207832493214425,
            "fields": {
                "feature_1": {
                    "field_config": {
                        "visible_name": "feature_1",
                        "field_name": "feature_1",
                        "field_type": "numeric",
                        "min_threshold": 0.0,
                        "max_threshold": 819.943,
                        "interval": 16.39886,
                        "metrics": [
                            "average"
                        ],
                        "percents": []
                    },
                    "average": 1.6747929020183223,
                    "sum": 700,
                    "variance": 11.07528219325513,
                    "normalized_variance": 6.612926398188166,
                    "std": 3.327954656129667,
                    "standard_error": 0.1627755829800218,
                    "min": 0.04216957092285156,
                    "max": 48.74291229248047,
                    "time_series_1d": {
                        "1619049600000": {
                            "amount": 57,
                            "ratio": 0.1532258064516129,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.2383997223356313,
                            "sum": 70,
                            "variance": 1.0220868944553085,
                            "normalized_variance": 0.8253287496929059,
                            "std": 1.0109831326265086,
                            "standard_error": 0.13390798716107913,
                            "min": 0.06524977087974548,
                            "max": 3.7492806911468506
                        },
                        "1619136000000": {
                            "amount": 64,
                            "ratio": 0.165374677002584,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.4505967439617962,
                            "sum": 92,
                            "variance": 2.167477433156669,
                            "normalized_variance": 1.494197089700453,
                            "std": 1.47223552231179,
                            "standard_error": 0.18402944028897375,
                            "min": 0.18442778289318085,
                            "max": 7.366733551025391
                        },
                        "1619222400000": {
                            "amount": 89,
                            "ratio": 0.16984732824427481,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.4759053633956427,
                            "sum": 131,
                            "variance": 13.69266633725633,
                            "normalized_variance": 9.277469055165813,
                            "std": 3.7003602983029005,
                            "standard_error": 0.39223740714607763,
                            "min": 0.04216957092285156,
                            "max": 35.26789093017578
                        },
                        "1619308800000": {
                            "amount": 52,
                            "ratio": 0.17391304347826086,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 2.414520780914105,
                            "sum": 125,
                            "variance": 44.908168174775945,
                            "normalized_variance": 18.59920549442292,
                            "std": 6.70135569678076,
                            "standard_error": 0.9293108299948362,
                            "min": 0.24495546519756317,
                            "max": 48.74291229248047
                        },
                        "1619395200000": {
                            "amount": 40,
                            "ratio": 0.16806722689075632,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.805921695753932,
                            "sum": 72,
                            "variance": 3.4229494408987664,
                            "normalized_variance": 1.8954030227040168,
                            "std": 1.850121466525581,
                            "standard_error": 0.2925298891095902,
                            "min": 0.13120442628860474,
                            "max": 10.157670974731445
                        },
                        "1619481600000": {
                            "amount": 61,
                            "ratio": 0.16442048517520216,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.6789902006504966,
                            "sum": 102,
                            "variance": 7.717022387918702,
                            "normalized_variance": 4.596228366865316,
                            "std": 2.7779529131932206,
                            "standard_error": 0.35568042360575897,
                            "min": 0.11447876691818237,
                            "max": 20.01999855041504
                        },
                        "1619568000000": {
                            "amount": 55,
                            "ratio": 0.14175257731958762,
                            "field_config": {
                                "visible_name": "feature_1",
                                "field_name": "feature_1",
                                "field_type": "numeric",
                                "min_threshold": 0.0,
                                "max_threshold": 819.943,
                                "interval": 16.39886,
                                "metrics": [
                                    "average"
                                ],
                                "percents": []
                            },
                            "average": 1.9103732588616285,
                            "sum": 105,
                            "variance": 4.021347505347108,
                            "normalized_variance": 2.10500617441818,
                            "std": 2.0053297747121563,
                            "standard_error": 0.27039861166087603,
                            "min": 0.14577417075634003,
                            "max": 9.384171485900879
                        }
                    },
                    "histogram": {
                        "0.0": 415,
                        "16.39886": 1,
                        "32.79772": 2,
                        "49.19658": 0,
                        "65.59544": 0,
                        "81.9943": 0,
                        "98.39316": 0,
                        "114.79202": 0,
                        "131.19088": 0,
                        "147.58974": 0,
                        "163.9886": 0,
                        "180.38745999999998": 0,
                        "196.78632": 0,
                        "213.18518": 0,
                        "229.58404": 0,
                        "245.98289999999997": 0,
                        "262.38176": 0,
                        "278.78062": 0,
                        "295.17948": 0,
                        "311.57833999999997": 0,
                        "327.9772": 0,
                        "344.37606": 0,
                        "360.77491999999995": 0,
                        "377.17377999999997": 0,
                        "393.57264": 0,
                        "409.9715": 0,
                        "426.37036": 0,
                        "442.76921999999996": 0,
                        "459.16808": 0,
                        "475.56694": 0,
                        "491.96579999999994": 0,
                        "508.36465999999996": 0,
                        "524.76352": 0,
                        "541.16238": 0,
                        "557.56124": 0,
                        "573.9601": 0,
                        "590.35896": 0,
                        "606.7578199999999": 0,
                        "623.1566799999999": 0,
                        "639.55554": 0,
                        "655.9544": 0,
                        "672.35326": 0,
                        "688.75212": 0,
                        "705.15098": 0,
                        "721.5498399999999": 0,
                        "737.9486999999999": 0,
                        "754.3475599999999": 0,
                        "770.74642": 0,
                        "787.14528": 0,
                        "803.54414": 0,
                        "819.943": 0
                    }
                }
            },
            "sampling_factor": 1,
            "failed_shards_factor": 1.0
        }
    },
    "partial_data": false
}

Did this page help you?