7.1 Location management APIs
29.5493GPPApplication Programming Interface (API) specificationRelease 18Service Enabler Architecture Layer for Verticals (SEAL)Stage 3TS
7.1.1 SS_LocationReporting API
7.1.1.1 API URI
The SS_LocationReporting service shall use the SS_LocationReporting API.
The request URIs used in HTTP requests from the VAL server towards the location management server shall have the Resource URI structure as defined in clause 6.5 with the following clarifications:
– The <apiName> shall be "ss-lr".
– The <apiVersion> shall be "v1".
– The <apiSpecificSuffixes> shall be set as described in clause 7.1.1.2.
7.1.1.2 Resources
7.1.1.2.1 Overview
This clause describes the structure for the Resource URIs and the resources and methods used for the service.
Figure 7.1.1.2.1-1 depicts the resource URIs structure for the SS_LocationReporting API.
Figure 7.1.1.2.1-1: Resource URI structure of the SS_LocationReporting API
Table 7.1.1.2.1-1 provides an overview of the resources and applicable HTTP methods.
Table 7.1.1.2.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
SEAL Location Reporting Configurations |
/trigger-configurations |
POST |
Creates a new Individual SEAL Location Reporting Configuration information. |
|
Individual SEAL Location Reporting Configuration |
/trigger-configurations/{configurationId} |
GET |
Retrieves an Individual SEAL Location Reporting Configuration information identified by {configurationId}. |
|
PUT |
Updates an Individual SEAL Location Reporting Configuration information identified by {configurationId}. |
||
|
PATCH |
Partially modifies an Individual SEAL Location Reporting Configuration information identified by {configurationId}. |
||
|
DELETE |
Delete an Individual SEAL Location Reporting Configuration information identified by {configurationId}. |
7.1.1.2.2 Resource: SEAL Location Reporting Configurations
7.1.1.2.2.1 Description
The resource allows the VAL server to request to create a new individual SEAL location reporting configuration information at the location management server.
7.1.1.2.2.2 Resource Definition
Resource URI: {apiRoot}/ss-lr/<apiVersion>/trigger-configurations
This resource shall support the resource URI variables defined in the table 7.1.1.2.2.2-1.
Table 7.1.1.2.2.2-1: Resource URI variables for this resource
|
Name |
Data Type |
Definition |
|
apiRoot |
string |
See clause 6.5 |
7.1.1.2.2.3 Resource Standard Methods
7.1.1.2.2.3.1 POST
Table 7.1.1.2.2.3.1-1: URI query parameters supported by the POST method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
This method shall support the request data structures specified in table 7.1.1.2.2.3.1-2 and the response data structures and response codes specified in table 7.1.1.2.2.3.1-3.
Table 7.1.1.2.2.3.1-2: Data structures supported by the POST Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
LocationReportConfiguration |
M |
1 |
Location reporting configuration information. |
Table 7.1.1.2.2.3.1-3: Data structures supported by the POST Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
LocationReportConfiguration |
M |
1 |
201 Created |
Location reporting configuration is created successfully. |
|
NOTE: The mandatory HTTP error status codes for the POST method listed in table 5.2.6-1 of 3GPP TS 29.122 [3] also apply. |
||||
Table 7.1.1.2.2.3.1-4: Headers supported by the 201 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
Contains the URI of the newly created resource, according to the structure: {apiRoot}/ss-lr/<apiVersion>/trigger-configurations/{configurationId} |
7.1.1.2.2.4 Resource Custom Operations
None.
7.1.1.2.3 Resource: Individual SEAL Location Reporting Configuration
7.1.1.2.3.1 Description
The resource represents an individual SEAL location reporting configuration that is created at the location management server.
7.1.1.2.3.2 Resource Definition
Resource URI: {apiRoot}/ss-lr/<apiVersion>/trigger-configurations/{configurationId}
This resource shall support the resource URI variables defined in the table 7.1.1.2.3.2-1.
Table 7.1.1.2.3.2-1: Resource URI variables for this resource
|
Name |
Data Type |
Definition |
|
apiRoot |
string |
See clause 6.5 |
|
configurationId |
string |
Represents an individual SEAL location reporting configuration resource. |
7.1.1.2.3.3 Resource Standard Methods
7.1.1.2.3.3.1 GET
This operation retrieves an individual SEAL location reporting configuration information. This method shall support the URI query parameters specified in table 7.1.1.2.3.3.1-1.
Table 7.1.1.2.3.3.1-1: URI query parameters supported by the GET method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
This method shall support the request data structures specified in table 7.1.1.2.3.3.1-2 and the response data structures and response codes specified in table 7.1.1.2.3.3.1-3.
Table 7.1.1.2.3.3.1-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 7.1.1.2.3.3.1-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
LocationReportConfiguration |
M |
1 |
200 OK |
The location reporting configuration information. |
|
n/a |
307 Temporary Redirect |
Temporary redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative location management server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative location management server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [3] also apply. |
||||
Table 7.1.1.2.3.3.1-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative location management server. |
Table 7.1.1.2.3.3.1-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative location management server. |
7.1.1.2.3.3.2 PUT
This operation updates the individual SEAL location reporting configuration. This method shall support the URI query parameters specified in table 7.1.1.2.3.3.2-1.
Table 7.1.1.2.3.3.2-1: URI query parameters supported by the PUT method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
This method shall support the request data structures specified in table 7.1.1.2.3.3.2-2 and the response data structures and response codes specified in table 7.1.1.2.3.3.2-3.
Table 7.1.1.2.3.3.2-2: Data structures supported by the PUT Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
LocationReportConfiguration |
M |
1 |
Updated details of the location reporting configuration. |
Table 7.1.1.2.3.3.2-3: Data structures supported by the PUT Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
LocationReportConfiguration |
M |
1 |
200 OK |
The configuration is updated successfully and the updated configuration information returned in the response. |
|
n/a |
204 No Content |
The location reporting configuration updated successfully. |
||
|
n/a |
307 Temporary Redirect |
Temporary redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative location management server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection, during resource modification. The response shall include a Location header field containing an alternative URI of the resource located in an alternative location management server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
NOTE: The mandatory HTTP error status codes for the PUT method listed in table 5.2.6-1 of 3GPP TS 29.122 [3] also apply. |
||||
Table 7.1.1.2.3.3.2-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative location management server. |
Table 7.1.1.2.3.3.2-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative location management server. |
7.1.1.2.3.3.3 DELETE
This operation deletes the individual SEAL location reporting configuration. This method shall support the URI query parameters specified in table 7.1.1.2.3.3.3-1.
Table 7.1.1.2.3.3.3-1: URI query parameters supported by the DELETE method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
This method shall support the request data structures specified in table 7.1.1.2.3.3.3-2 and the response data structures and response codes specified in table 7.1.1.2.3.3.3-3.
Table 7.1.1.2.3.3.3-2: Data structures supported by the DELETE Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 7.1.1.2.3.3.3-3: Data structures supported by the DELETE Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
204 No Content |
The individual configuration matching the configurationId is deleted. |
||
|
n/a |
307 Temporary Redirect |
Temporary redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative location management server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative location management server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
NOTE: The mandatory HTTP error status codes for the DELETE method listed in table 5.2.6-1 of 3GPP TS 29.122 [3] also apply. |
||||
Table 7.1.1.2.3.3.3-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative location management server. |
Table 7.1.1.2.3.3.3-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative location management server. |
7.1.1.2.3.3.4 PATCH
This method shall support the URI query parameters specified in table 7.1.1.2.3.3.4-1.
Table 7.1.1.2.3.3.4-1: URI query parameters supported by the PATCH method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
n/a |
This method shall support the request data structures specified in table 7.1.1.2.3.3.4-2 and the response data structures and response codes specified in table 7.1.1.2.3.3.4-3.
Table 7.1.1.2.3.3.4-2: Data structures supported by the PATCH Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
LocationReportConfigurationPatch |
M |
1 |
Contains the modifications to be applied to the Individual SEAL Location Reporting Configuration resource. |
Table 7.1.1.2.3.3.4-3: Data structures supported by the PATCH Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
LocationReportConfiguration |
M |
1 |
200 OK |
Individual SEAL Location Reporting Configuration resource is modified successfully and representation of the modified Individual SEAL Location Reporting Configuration resource is returned. |
|
n/a |
204 No Content |
The Individual SEAL Location Reporting Configuration resource is updated successfully. |
||
|
n/a |
307 Temporary Redirect |
Temporary redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SEAL server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection, during resource termination. The response shall include a Location header field containing an alternative URI of the resource located in an alternative SEAL server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
NOTE: The mandatory HTTP error status codes for the PATCH method listed in table 5.2.6-1 of 3GPP TS 29.122 [3] also apply. |
||||
Table 7.1.1.2.3.3.4-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative SEAL server. |
Table 7.1.1.2.3.3.4-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative SEAL server. |
7.1.1.2.3.4 Resource Custom Operations
None.
7.1.1.3 Notifications
None.
7.1.1.4 Data Model
7.1.1.4.1 General
This clause specifies the application data model supported by the API. Data types listed in clause 6.2 apply to this API.
Table 7.1.1.4.1-1 specifies the data types defined specifically for the SS_LocationReporting API service.
Table 7.1.1.4.1-1: SS_LocationReporting API specific Data Types
|
Data type |
Section defined |
Description |
Applicability |
|
LocationReportConfiguration |
7.1.1.4.2.2 |
Represents the location reporting configuration information. |
|
|
LocationReportConfigurationPatch |
7.1.1.4.2.3 |
Represents the requested modifications to the location reporting configuration information. Used to partially update Individual SEAL Location Reporting Configuration resource. |
PatchUpdate |
Table 7.1.1.4.1-2 specifies data types re-used by the SS_LocationReporting API service.
Table 7.1.1.4.1-2: SS_LocationReporting API Re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
Accuracy |
3GPP TS 29.122 [3] |
Used to represent the desired level of accuracy of the requested location information. |
|
|
DateTime |
3GPP TS 29.571 [21] |
Used to represent the subscription duration. |
|
|
DurationSec |
3GPP TS 29.571 [21] |
Used to represent the time interval between successive location reports. |
|
|
SupportedFeatures |
3GPP TS 29.571 [21] |
Used to negotiate the applicability of optional features defined in table 7.1.1.6-1. |
|
|
ValTargetUe |
Clause 7.3.1.4.2.3 |
Used to indicate either VAL User ID or VAL UE ID, to which location reporting applies. |
7.1.1.4.2 Structured data types
7.1.1.4.2.1 Introduction
7.1.1.4.2.2 Type: LocationReportConfiguration
Table 7.1.1.4.2.2-1: Definition of type LocationReportConfiguration
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
valServerId |
string |
M |
1 |
Represents the VAL server identifier. |
|
|
valTgtUe |
ValTargetUe |
M |
1 |
Represents the VAL User ID or VAL UE ID to which the location reporting applies. |
|
|
immRep |
boolean |
O |
0..1 |
Indication of immediate reporting. If included, when it is set to true it indicates immediate reporting of the subscribed events, if available. Otherwise, reporting will occur when the event is met. |
|
|
monDur |
DateTime |
O |
0..1 |
Represents the time at which the subscription ceases to exist (i.e the reporting trigger becomes invalid). If omitted, there is no time limit. |
|
|
repPeriod |
DurationSec |
O |
0..1 |
Indicates the time interval between successive location reports. |
|
|
accuracy |
Accuracy |
O |
0..1 |
Represents the desired level of accuracy of the requested location information. |
|
|
suppFeat |
SupportedFeatures |
O |
0..1 |
Used to negotiate the supported features of the API as defined in clause 7.1.1.6. This attribute shall be provided in the HTTP POST request and in the response of successful resource creation. |
7.1.1.4.2.3 Type: LocationReportConfigurationPatch
Table 7.1.1.4.2.3-1: Definition of type LocationReportConfigurationPatch
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
valTgtUe |
ValTargetUe |
O |
1 |
Represents the VAL User ID or VAL UE ID to which the location reporting applies. |
|
|
monDur |
DateTime |
O |
0..1 |
Represents the time at which the subscription ceases to exist (i.e the reporting trigger becomes invalid). If omitted, there is no time limit. |
|
|
repPeriod |
DurationSec |
O |
0..1 |
Indicates the time interval between successive location reports. |
|
|
accuracy |
Accuracy |
O |
0..1 |
Represents the desired level of accuracy of the requested location information. |
7.1.1.4.3 Simple data types and enumerations
7.1.1.5 Error Handling
7.1.1.5.1 General
HTTP error handling shall be supported as specified in clause 6.7.
In addition, the requirements in the following clauses shall apply.
7.1.1.5.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the SS_LocationReporting API.
7.1.1.5.3 Application Errors
The application errors defined for SS_LocationReporting API are listed in table 7.1.1.5.3-1.
Table 7.1.1.5.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
Applicability |
7.1.1.6 Feature negotiation
General feature negotiation procedures are defined in clause 6.8.
Table 7.1.1.6-1: Supported Features
|
Feature number |
Feature Name |
Description |
|
1 |
PatchUpdate |
Indicates the support of the PATCH method for updating an Individual SEAL Location Reporting Configuration resource. |
7.1.2 SS_LocationAreaInfoRetrieval API
7.1.2.1 API URI
The request URI used in each HTTP request from the VAL server towards the location management server shall have the structure as defined in clause 6.5 with the following clarifications:
– The <apiName> shall be "ss-lair".
– The <apiVersion> shall be "v1".
– The <apiSpecificSuffixes> shall be set as described in clause 7.1.2.2.
7.1.2.2 Resources
7.1.2.2.1 Overview
This clause describes the structure for the Resource URIs and the resources and methods used for the service.
Figure 7.1.2.2.1-1 depicts the resource URIs structure for the SS_LocationAreaInfoRetrieval API.
Figure 7.1.2.2.1-1: Resource URI structure of the SS_LocationAreaInfoRetrieval API
Table 7.1.2.2.1-1 provides an overview of the resources and applicable HTTP methods.
Table 7.1.2.2.1-1: Resources and methods overview
|
Resource name |
Resource URI |
HTTP method or custom operation |
Description |
|
Location Information |
/location-retrievals |
GET |
Obtains the UE(s) information in an application defined proximity range of a location. |
7.1.2.2.2 Resource: Location Information
7.1.2.2.2.1 Description
The Location Information resource represents the collection of UE(s) location information at the location management server.
7.1.2.2.2.2 Resource Definition
Resource URI: {apiRoot}/ss-lair/<apiVersion>/location-retrievals
This resource shall support the resource URI variables defined in the table 7.1.2.2.2.2-1.
Table 7.1.2.2.2.2-1: Resource URI variables for this resource
|
Name |
Data Type |
Definition |
|
apiRoot |
string |
See clause 6.5 |
7.1.2.2.2.3 Resource Standard Methods
7.1.2.2.2.3.1 GET
This operation obtains the UE(s) information in an application defined proximity range of a location. This method shall support the URI query parameters specified in table 7.1.2.2.2.3.1-1.
Table 7.1.2.2.2.3.1-1: URI query parameters supported by the GET method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
location-info |
LocationInfo |
M |
1 |
Location information around which the UE(s) information is requested. |
|
range |
Float |
M |
1 |
The range information over which the UE(s) information is required, expressed in meters. Minimum = 0 |
This method shall support the request data structures specified in table 7.1.2.2.2.3.1-2 and the response data structures and response codes specified in table 7.1.2.2.2.3.1-3.
Table 7.1.2.2.2.3.1-2: Data structures supported by the GET Request Body on this resource
|
Data type |
P |
Cardinality |
Description |
|
n/a |
Table 7.1.2.2.2.3.1-3: Data structures supported by the GET Response Body on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
array(LMInformation) |
O |
1..N |
200 OK |
The UE(s) information in an application defined proximity range of a location |
|
n/a |
307 Temporary Redirect |
Temporary redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative location management server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
n/a |
308 Permanent Redirect |
Permanent redirection, during resource retrieval. The response shall include a Location header field containing an alternative URI of the resource located in an alternative location management server. Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [3]. |
||
|
NOTE: The mandatory HTTP error status codes for the GET method listed in table 5.2.6-1 of 3GPP TS 29.122 [3] also apply. |
||||
Table 7.1.2.2.2.3.1-4: Headers supported by the 307 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative location management server. |
Table 7.1.2.2.2.3.1-5: Headers supported by the 308 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location |
string |
M |
1 |
An alternative URI of the resource located in an alternative location management server. |
7.1.2.2.2.4 Resource Custom Operations
None.
7.1.2.3 Notifications
None.
7.1.2.4 Data Model
7.1.2.4.1 General
This clause specifies the application data model supported by the API. Data types listed in clause 6.2 apply to this API.
Table 7.1.2.4.1-1 specifies the data types defined specifically for the SS_LocationAreaInfoRetrieval API service.
Table 7.1.2.4.1-1: SS_LocationAreaInfoRetrieval API specific Data Types
|
Data type |
Section defined |
Description |
Applicability |
Table 7.1.2.4.1-2 specifies data types re-used by the SS_LocationAreaInfoRetrieval API service.
Table 7.1.2.4.1-2: Re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
Float |
3GPP TS 29.571 [21] |
Used to represent the value of the range. |
|
|
LMInformation |
7.5.1.4.2.8 |
Used to represent the location information for a VAL User ID or a VAL UE ID. |
|
|
LocationInfo |
3GPP TS 29.122 [3] |
Used to represent the location information. |
7.1.2.4.2 Structured Data Types
None.
7.1.2.4.3 Simple data types and enumerations
None.
7.1.2.5 Error Handling
7.1.2.5.1 General
HTTP error handling shall be supported as specified in clause 6.7.
In addition, the requirements in the following clauses shall apply.
7.1.2.5.2 Protocol Errors
In this Release of the specification, there are no additional protocol errors applicable for the SS_LocationAreaInfoRetrieval API.
7.1.2.5.3 Application Errors
The application errors defined for SS_LocationAreaInfoRetrieval API are listed in table 7.1.2.5.3-1.
Table 7.1.2.5.3-1: Application errors
|
Application Error |
HTTP status code |
Description |
Applicability |
7.1.2.6 Feature Negotiation
General feature negotiation procedures are defined in clause 6.8.
Table 7.1.2.6-1: Supported Features
|
Feature number |
Feature Name |
Description |