CreateLocationDateClusteringTask - Intelligent Media Management

The spatio-temporal clustering feature classifies files in a dataset based on their time and location. This feature works on indexed files, such as images and videos, that contain shooting time and location data. These classifications can represent content from a user's trip, where files have similar timestamps and locations. The classifications can also represent content shot at different places where a user lives or works. Analyzing the locations and time ranges of these classifications lets you categorize media files, create highlight reels, and generate photo and video stories.

Operation description

Before you use this operation, you must understand the billing methods and pricing of Intelligent Media Management (IMM).
Important Asynchronous tasks do not have a guaranteed processing time.
Before you call this operation, you must index files into a dataset. You can index files by binding data sources using CreateBinding or by indexing files using IndexFileMeta or BatchIndexFileMeta.
Each call to this operation processes the files in the specified Dataset incrementally. You can call this operation periodically to process new files.
After clustering is complete, you can call the QueryLocationDateClusters operation to retrieve the clustering results.
Deleting a file from a dataset does not change the spatio-temporal clusters. To delete existing spatio-temporal clusters, you can call the DeleteLocationDateCluster operation.
This is an asynchronous operation. After a task starts, its information is saved for only 7 days. You cannot retrieve task information after 7 days. You can call the GetTask or ListTasks operation to view task information using the returned TaskId. You can also configure the Notification parameter to receive task information through message notifications.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

imm:CreateLocationDateClusteringTask

create

*Dataset

acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}/dataset/{#DatasetName}

None

Request parameters

Parameter	Type	Required	Description	Example
ProjectName	string	Yes	The project name. For more information, see Create a project.	test-project
DatasetName	string	Yes	The dataset name. For more information, see Create a dataset.	test-dataset
UserData	string	No	Custom information that is returned in the asynchronous notification message. This helps you associate the notification message with your system. The maximum length is 2,048 bytes.	test-data
Tags	object	No	Custom tags used to search for and filter asynchronous tasks.	{ "User": "Jane" }
DateOptions	object	Yes	The date clustering settings. Important Modifying this setting also affects existing spatio-temporal clusters in your `Dataset`.
GapDays	integer	Yes	The maximum number of gap days allowed in a single spatio-temporal group. The value must be in the range of 0 to 99,999. For example, a user has photos from March 4–5 and March 7, but not from March 6. If you assume that the photos from March 4–7 belong to the same trip, set this parameter to `1 day`. This allows the gap of `1 day` on March 6 to be included in the same spatio-temporal cluster. Set this parameter to a value from 0 to 3.	1
MinDays	integer	Yes	The minimum number of days in a single spatio-temporal group. The value must be in the range of 1 to 99,999. Clusters with fewer days than this value are not detected or stored. For example, if you do not want to include one-day trips in the generated groups, set this parameter to 2.	1
MaxDays	integer	Yes	The maximum number of days in a single spatio-temporal group. The value must be in the range of 1 to 99,999. Clusters with more days than this value are not detected or stored. For example, if a user takes photos in the same location for more than 15 consecutive days, this location might be their residence rather than a travel destination. If you want to exclude this time period and location from the spatio-temporal clusters, set this parameter to 15.	15
LocationOptions	object	Yes	The location clustering settings. Important Modifying this setting also affects existing spatio-temporal clusters in your `Dataset`.
LocationDateClusterLevels	array	Yes	A list of administrative levels for grouping. You can select multiple levels. For example, a user uploads photos taken in Hangzhou from March 3 to March 5 and photos taken in Jiaxing from March 6 to March 8. If you set this parameter to `["city", "province"]`, the following spatio-temporal clusters are generated: March 3 to March 5, Hangzhou March 6 to March 8, Jiaxing March 3 to March 8, Zhejiang
	string	Yes	The administrative level for grouping. Valid values: country : Country or region province : Province city : City district : District township : Township	province
Notification	Notification	No	The message notification configuration. For more information, see Notification. For the format of asynchronous notification messages, see Asynchronous notification message format.

Response elements

Element	Type	Description	Example
	object	The information about the spatio-temporal clustering task.
RequestId	string	The ID of the request.	B121940C-9794-4EE3-8D6E-F8EC525F****
TaskId	string	The task ID.	LocationDateClustering-c10dce07-1de7-4da7-abee-1a3aba7****
EventId	string	The event ID.	25B-1W2ChgujA3Q8MbBY6mSp2mh****

Examples

Success response

JSON format

{
  "RequestId": "B121940C-9794-4EE3-8D6E-F8EC525F****",
  "TaskId": "LocationDateClustering-c10dce07-1de7-4da7-abee-1a3aba7****",
  "EventId": "25B-1W2ChgujA3Q8MbBY6mSp2mh****"
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.