{"name":"projects/timeseries-staging/locations/us-central1/datasets/webnlp-201901-202104-dragosd","slices":[{"dimensions":[{"name":"EntityLOCATION","stringVal":"Notre Dame"}],"detectionPointActual":1514,"detectionPointForecast":15.5,"expectedDeviation":5.5,"anomalyScore":14.203791469194313,"status":{}},{"dimensions":[{"name":"EntityLOCATION","stringVal":"Seine"}],"detectionPointActual":1113,"detectionPointForecast":14,"expectedDeviation":15,"anomalyScore":9.5565217391304351,"status":{}},{"dimensions":[{"name":"EntityLOCATION","stringVal":"Ile de la Cite"}],"detectionPointActual":852,"detectionPointForecast":0,"expectedDeviation":1,"anomalyScore":8.435643564356436,"status":{}},{"dimensions":[{"name":"EntityLOCATION","stringVal":"Paris"}],"detectionPointActual":1461,"detectionPointForecast":857,"expectedDeviation":441,"anomalyScore":1.1164510166358594,"status":{}},{"dimensions":[{"name":"EntityLOCATION","stringVal":"France"}],"detectionPointActual":1098,"detectionPointForecast":950.5,"expectedDeviation":476.5,"anomalyScore":0.25585429314830876,"status":{}}]}
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-27。"],[],[],null,["# Tutorial\n\n*** ** * ** ***\n\nWe use a small dataset provided by\n[Kalev Leetaru](https://www.kalevleetaru.com/) to illustrate the Timeseries\nInsights API. The dataset is derived from\n[The GDELT Project](https://www.gdeltproject.org/), a global database tracking\nworld events and media coverage. This dataset contains entity mentionings in\nnews URLs in April 2019.\n\nObjectives\n----------\n\n- Learn the data format for Timeseries Insights API.\n- Learn how to create, query, update and delete datasets.\n\nBefore you begin\n----------------\n\nSet up a Cloud project and enable Timeseries Insights API following\n[Setup for Full Access](/timeseries-insights/docs/getting-started). \n\nTutorial dataset\n----------------\n\nThe dataset includes entity annotations of locations, organizations, persons,\namong others.\n\nThe Timeseries Insights API takes JSON format inputs. A sample\n[Event](/timeseries-insights/docs/reference/rest/v1/projects.locations.datasets/appendEvents#event)\nfor this dataset is \n\n {\n \"groupId\":\"-6180929807044612746\",\n \"dimensions\":[{\"name\":\"EntityORGANIZATION\",\"stringVal\":\"Medina Gazette\"}],\n \"eventTime\":\"2019-04-05T08:00:00+00:00\"\n }\n\nEach event must have an `eventTime` field for the event timestamp. It is preferred\neach event also has a long-valued `groupId` to mark related events. Event\nproperties are included as `dimensions`, each of which has a `name` and one of\n`stringVal`, `boolVal`, `longVal`, or `doubleVal`.\n| **Note:** Google Cloud APIs accept both camel case (like `camelCase`) and snake case (like `snake_case`) for JSON field names. The documentations are mostly written as camel case.\n| **Note:** Since JSON long values (numbers) are actually float values with only integer precisions, both `groupId` and `longVal` are effectively limited to 53 binary digits if JSON uses numbers. To provide int64 data, the JSON value should be quoted as a string. A `groupId` is typically a numerical ID or generated with a deterministic hash function, satisfying the above restriction.\n| **Note:** The `name` field is supposed to be alphanumerical values including `'_'`. Special characters including the space are not supported. The `stringVal` field supports valid Unicode characters.\n**Note:** When reading from a static Google Cloud Storage data source each JSON event is supposed to be a single line (also known as JSON-line format) as follows: \n\n {\"groupId\":\"-6180929807044612746\",\"dimensions\":[{\"name\":\"EntityORGANIZATION\",\"stringVal\":\"Medina Gazette\"}],\"eventTime\":\"2019-04-05T08:00:00+00:00\"}\n\nList datasets\n-------------\n\n[projects.locations.datasets.list](/timeseries-insights/docs/reference/rest/v1/projects.locations.datasets/list)\nshows all datasets under `${PROJECT_ID}`. `gcurl` is an alias and\n`PROJECT_ID` is an environment variable, both set up in\n[Getting Started](/timeseries-insights/docs/getting-started). \n\n gcurl https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets\n\nThe result is a JSON string like \n\n {\n \"datasets\": [\n {\n \"name\": \"example\",\n \"state\": \"LOADED\",\n ...\n },\n {\n \"name\": \"dataset_tutorial\",\n \"state\": \"LOADING\",\n ...\n }\n ]\n }\n\nThe results show the datasets currently under the project. The `state` field\nindicates whether the dataset is ready to be used. When a dataset is just\ncreated, it is in state `LOADING` until the indexing completes, then transitions\nto `LOADED` state. If any errors occur during creation and indexing, it will be\nin `FAILED` state. The results also include the complete dataset information\nfrom the original create request.\n\nCreate dataset\n--------------\n\n[projects.locations.datasets.create](/timeseries-insights/docs/reference/rest/v1/projects.locations.datasets/create)\nadds a new dataset to the project. \n\n gcurl -X POST -d @create.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets\n\nwhere `create.json` contains: \n\n {\n name: \"dataset_tutorial\",\n dataNames: [\n \"EntityCONSUMER_GOOD\",\n \"EntityEVENT\",\n \"EntityLOCATION\",\n \"EntityORGANIZATION\",\n \"EntityOTHER\",\n \"EntityPERSON\",\n \"EntityUNKNOWN\",\n \"EntityWORK_OF_ART\",\n ],\n dataSources: [\n {uri: \"gs://data.gdeltproject.org/blog/2021-timeseries-insights-api/datasets/webnlp-201904.json\"}\n ]\n }\n\nThis request creates a dataset named `dataset_tutorial` from GCS\n`dataSources`, which contain Event data in JSON format. Only dimensions listed\nin `dataNames` are indexed and used by the system.\n\nThe create request returns success if it is accepted by the API server. The\ndataset will be in `LOADING` state until indexing completes, then the state\nbecomes `LOADED`, after which the dataset can start accepting queries and\nupdates if any.\n| **Note:** Make sure the project has proper read permissions to `dataSources`. Otherwise, indexing fails with `PERMISSION_DENIED` or `NOT_FOUND`.\n\nQuery dataset\n-------------\n\n[projects.locations.datasets.query](/timeseries-insights/docs/reference/rest/v1/projects.locations.datasets/query)\nperforms anomaly detection queries. \n\n gcurl -X POST -d @query.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:query\n\nwhere `query.json` contains: \n\n {\n \"detectionTime\": \"2019-04-15T00:00:00Z\",\n \"numReturnedSlices\": 5,\n \"slicingParams\": {\n \"dimensionNames\": [\"EntityLOCATION\"]\n },\n \"timeseriesParams\": {\n \"forecastHistory\": \"1209600s\",\n \"granularity\": \"86400s\"\n },\n \"forecastParams\": {\n \"noiseThreshold\": 100.0\n },\n }\n\nThe query result looks like follows: \n\n {\n \"name\": \"projects/timeseries-staging/locations/us-central1/datasets/webnlp-201901-202104-dragosd\",\n \"slices\": [\n {\n \"dimensions\": [\n {\n \"name\": \"EntityLOCATION\",\n \"stringVal\": \"Notre Dame\"\n }\n ],\n \"detectionPointActual\": 1514,\n \"detectionPointForecast\": 15.5,\n \"expectedDeviation\": 5.5,\n \"anomalyScore\": 14.203791469194313,\n \"status\": {}\n },\n {\n \"dimensions\": [\n {\n \"name\": \"EntityLOCATION\",\n \"stringVal\": \"Seine\"\n }\n ],\n \"detectionPointActual\": 1113,\n \"detectionPointForecast\": 14,\n \"expectedDeviation\": 15,\n \"anomalyScore\": 9.5565217391304351,\n \"status\": {}\n },\n {\n \"dimensions\": [\n {\n \"name\": \"EntityLOCATION\",\n \"stringVal\": \"Ile de la Cite\"\n }\n ],\n \"detectionPointActual\": 852,\n \"detectionPointForecast\": 0,\n \"expectedDeviation\": 1,\n \"anomalyScore\": 8.435643564356436,\n \"status\": {}\n },\n {\n \"dimensions\": [\n {\n \"name\": \"EntityLOCATION\",\n \"stringVal\": \"Paris\"\n }\n ],\n \"detectionPointActual\": 1461,\n \"detectionPointForecast\": 857,\n \"expectedDeviation\": 441,\n \"anomalyScore\": 1.1164510166358594,\n \"status\": {}\n },\n {\n \"dimensions\": [\n {\n \"name\": \"EntityLOCATION\",\n \"stringVal\": \"France\"\n }\n ],\n \"detectionPointActual\": 1098,\n \"detectionPointForecast\": 950.5,\n \"expectedDeviation\": 476.5,\n \"anomalyScore\": 0.25585429314830876,\n \"status\": {}\n }\n ]\n }\n\nStreaming update\n----------------\n\n[projects.locations.datasets.appendEvents](/timeseries-insights/docs/reference/rest/v1/projects.locations.datasets/appendEvents)\nadds Event records in a streaming fashion. \n\n gcurl -X POST -d @append.json https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial:appendEvents\n\nwhere `append.json` contains (please replace `eventTime` to a timestamp close to the present time): \n\n {\n events: [\n {\n \"groupId\":\"1324354349507023708\",\n \"dimensions\":[{\"name\":\"EntityPERSON\",\"stringVal\":\"Jason Marsalis\"}],\n \"eventTime\":\"2022-02-16T15:45:00+00:00\"\n },{\n \"groupId\":\"1324354349507023708\",\n \"dimensions\":[{\"name\":\"EntityORGANIZATION\",\"stringVal\":\"WAFA\"}],\n \"eventTime\":\"2022-02-16T04:00:00+00:00\"\n }\n ]\n }\n\nStreamed updates get indexed near-real time so changes can respond quickly in\nquery results. All events sent by a single\n[projects.locations.datasets.appendEvents](/timeseries-insights/docs/reference/rest/v1/projects.locations.datasets/appendEvents)\nrequest must have the same `groupdId`.\n\nDelete dataset\n--------------\n\n[projects.locations.datasets.delete](/timeseries-insights/docs/reference/rest/v1/projects.locations.datasets/delete)\nmarks the dataset for deletion. \n\n gcurl -X DELETE https://timeseriesinsights.googleapis.com/v1/projects/${PROJECT_ID}/datasets/dataset_tutorial\n\nThe request returns immediately, and the dataset will not accept additional\nqueries or updates. It may take sometime before the data is completely removed\nfrom the service, after which List datasets will not return this dataset.\n\nWhat's next\n-----------\n\n- Timeseries Insights API [Concepts](/timeseries-insights/docs/concept)\n- Learn more about the [REST API](/timeseries-insights/docs/reference/rest/v1/projects.locations.datasets)\n\nSome other examples can be found on\n[the GDELT website](https://blog.gdeltproject.org/) by searching for \"Timeseries\nInsights API\"."]]
