Location Information Subscriptions

/subscriptions

POST

Creates a subscription for continuous reporting of UE(s) location information to the EAS.

Individual Location Information Subscription

/subscriptions/{subscriptionId}

GET

Retrieves the Individual location information subscription information identified by subscriptionId.

PATCH

Partially updates the Individual location information subscription identified by subscriptionId.

PUT

Fully replace the Individual location information subscription identified by subscriptionId.

DELETE

Removes the Individual location information subscription identified by subscriptionId.

apiRoot

string

See clause 7.5

n/a

LocationSubscription

M

1

Create a new location information subscription.

LocationSubscription

M

1

201 Created

The individual location information subscription resource created successfully. The information about the confirmed subscription at the EES is provided in the response body.

The URI of the created resource shall be returned in the "Location" HTTP header.

ProblemDetails

O

0..1

403 Forbidden

(NOTE 2)

NOTE 1: The mandatory HTTP error status code for the POST method listed in Table 5.2.6-1 of 3GPP TS 29.122 [6] also apply.

NOTE 2: Failure cases are described in clause 8.2.6.3.

Location

string

M

1

Contains the URI of the newly created resource, according to the structure:

{apiRoot}/eees-uelocation/<apiVersion>/subscriptions/{subscriptionId}

apiRoot

string

See clause 7.5

subscriptionId

string

Identifies an individual location information subscription.

n/a

n/a

LocationSubscription

M

1

200 OK

The location information subscription information is returned by the EES.

n/a

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

n/a

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

NOTE: The manadatory HTTP error status code for the GET method listed in Table 5.2.6-1 of 3GPP TS 29.122 [6] also apply.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

n/a

LocationSubscriptionPatch

M

1

Request to partially update the individual location information subscription matching the subscriptionId at the EES.

LocationSubscription

M

1

200 OK

The individual Location information subscription matching the subscriptionId was modified successfully and the updated Location subscription information is returned in the response.

n/a

204 No Content

The individual Location information subscription matching the subscriptionId was modified successfully.

n/a

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

n/a

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

ProblemDetails

O

0..1

403 Forbidden

(NOTE 2)

NOTE 1: The manadatory HTTP error status code for the PATCH method listed in Table 5.2.6-1 of 3GPP TS 29.122 [6] also apply.

NOTE 2: Failure cases are described in clause 8.2.6.3.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

n/a

LocationSubscription

M

1

Details of individual location information subscription matching the subscriptionId to be updated at the EES.

LocationSubscription

M

1

200 OK

The individual Location information subscription matching the subscriptionId was modified successfully and the updated Location subscription information is returned in the response.

n/a

204 No Content

The individual Location information subscription matching the subscriptionId was modified successfully.

n/a

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

n/a

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

ProblemDetails

O

0..1

403 Forbidden

(NOTE 2)

NOTE 1: The manadatory HTTP error status code for the PUT method listed in Table 5.2.6-1 of 3GPP TS 29.122 [6] also apply.

NOTE 2: Failure cases are described in clause 8.2.6.3.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

n/a

n/a

n/a

M

1

204 No Content

The individual Location information subscription matching the subscriptionId is deleted.

n/a

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

n/a

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

NOTE: The mandatory HTTP error status code for the DELETE method listed in Table 5.2.6-1 of 3GPP TS 29.122 [6] also apply.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

Fetch

/fetch

POST

Fetch an UE location information.

LocationRequest

M

1

Parameters to request to fetch the UE location information.

LocationResponse

M

1

200 OK

Upon success, the UE location information returned by the EES.

n/a

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

n/a

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing an alternative URI of the resource located in an alternative EES.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

ProblemDetails

O

0..1

403 Forbidden

(NOTE 2)

NOTE 1: The manadatory HTTP error status code for the POST method listed in the Table 5.2.6-1 of 3GPP TS 29.122 [6] also apply.

NOTE 2: Failure cases are described in clause 8.2.6.3.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

Location

string

M

1

An alternative URI of the resource located in an alternative EES.

Location Information Notification

{notificationDestination}

POST

Notifies the subscriber EAS the UE(s) location information.

User Consent Revocation Notification

{revocationNotifUri}

POST

The user consent revocation notification from the EES to the EAS to inform about the revocation of user consent for one or several UE(s).

notificationDestination

Uri

Callback reference provided by the EAS during the UE location information subscription creation/update/modification procedure.

LocationNotification

M

1

Notification of UE(s) location information.

n/a

204 No Content

The receipt of the Notification is acknowledged.

n/a

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing an alternative URI representing the end point of an alternative EAS where the notification should be sent.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

n/a

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing an alternative URI representing the end point of an alternative EAS where the notification should be sent.

Redirection handling is described in clause 5.2.10 of TS 29.122 [6].

NOTE: The manadatory HTTP error status code for the POST method listed in Table 5.2.6-1 of 3GPP TS 29.122 [6] also apply.

Location

string

M

1

An alternative URI representing the end point of an alternative EAS towards which the notification should be redirected.

Location

string

M

1

An alternative URI representing the end point of an alternative EAS towards which the notification should be redirected.

revocationNotifUri

Uri

Callback reference provided by the EAS during the UE location information subscription creation or modification procedure if the UserConsentRevocation feature is supported, within the LocationSubscription data structure as specified in clauses 8.2.2.2.3.1, 8.2.2.3.3.3 and 8.2.5.2.2, or the LocationSubscriptionPatch data structure as specified in clauses 8.2.2.3.3.2, and 8.2.5.2.3.

ConsentRevocNotif

M

1

Contains the user consent revocation information.

n/a

204 No Content

Successful case. The user consent revocation notification is successfully received.

n/a

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing an alternative URI representing the end point of an alternative EAS where the notification should be sent.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6].

n/a

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing an alternative URI representing the end point of an alternative EAS where the notification should be sent.

Redirection handling is described in clause 5.2.10 of 3GPP TS 29.122 [6].

NOTE: The manadatory HTTP error status code for the HTTP POST method listed in Table 5.2.6-1 of TS 29.122 [6] also apply.

Location

string

1

An alternative URI representing the end point of an alternative EAS towards which the notification should be redirected.

Location

string

1

An alternative URI representing the end point of an alternative EAS towards which the notification should be redirected.

ConsentRevoked

8.2.5.2.9

Represents the information related to revoked user consent(s).

UserConsentRevocation

ConsentRevocNotif

8.2.5.2.8

Represents the user consent revocation information conveyed in a user consent revocation notification.

UserConsentRevocation

LocationSubscription

8.2.5.2.2

Represents the location information subscription.

LocationSubscriptionPatch

8.2.5.2.3

Used to request the partial update of location information subscription.

LocationNotification

8.2.5.2.4

UE location information notification from EES to EAS.

LocationEvent

8.2.5.2.5

Location information related an Individual UE.

LocationRequest

8.2.5.2.6

UE location information request

LocationResponse

8.2.5.2.7

Contains the response to a UE location information retrieval request.

Gpsi

3GPP TS 29.571 [8]

Used to identify the UE in the query parameter, for which location information is queried.

LocationQoS

3GPP TS 29.572 [11]

Used to indicate the location quality of service, of the location information queried.

LocationInfo

3GPP TS 29.122 [6]

The location information related to the UE .

DateTime

3GPP TS 29.122 [6]

Used to capture the expiration time of EAS subscription for location information reporting.

ReportingInformation

3GPP TS 29.523 [13]

Used to indicate the reporting requirement, only the following information are applicable:

– immRep

– notifMethod

– maxReportNbr

– monDur

– repPeriod

SupportedFeatures

3GPP TS 29.571 [8]

Used to negotiate the applicability of optional features.

TestNotification

3GPP TS 29.122 [6]

Following differences apply:

– The SCEF is the EES; and

– The SCS/AS is the subscribing EAS.

UcPurpose

3GPP TS 29.503 [22]

Represents the purpose of a user consent.

UserConsentRevocation

Uri

3GPP TS 29.122 [6]

WebsockNotifConfig

3GPP TS 29.122 [6]

Following differences apply:

– The SCEF is the EES; and

– The SCS/AS is the subscribing EAS.

UeMobilityExposure

3GPP TS 29.522 [10]

The predictive location information related to the UE,

GroupId

3GPP TS 29.571 [8]

Used to present the internal group identifier in location subscription.

ExternalId

TS 29.122 [6]

Represents an external identifier.

ExternalGroupId

3GPP TS 29.571 [8]

Used to present the external group identifier in location subscription.

Accuracy

3GPP TS 29.122 [6]

Used by EAS to indicate the desired granularity of the requested location information.

easId

string

M

1

The application identifier of the EAS, e.g. URI, FQDN, subscribing for location information report.

ueId

Gpsi

O

0..1

Identifier of the UE for which the location information reporting is subscribed for. (NOTE)

intGrpId

GroupId

O

0..1

The internal group identifier, identifying the group of UEs for which the location information reporting is subscribed for. (NOTE)

extGrpId

ExternalGroupId

O

0..1

The external group identifier, identifying the group of UEs for which the location information reporting is subscribed for. (NOTE)

expTime

DateTime

O

0..1

Indicates the expiration time of the subscription. If the expiration time is not present, then it indicates that the EAS subscription never expires.

locGran

Accuracy

O

0..1

Indicates the format of the location information that the EAS supports. EAS wishes to receive the location information report from the EES in the indicated format.

locQos

LocationQoS

O

0..1

Indicates the location QoS as specified in 3GPP TS 29.572 [11].

eventReq

ReportingInformation

O

0..1

Represents the reporting requirements of the location information event subscription.

notificationDestination

Uri

C

0..1

URI where the location information notification should be delivered to. This attribute shall be present in HTTP POST message to EES and shall be present in HTTP PUT request.

revocationNotifUri

Uri

C

0..1

Contains the URI via which the EAS desires to receive user consent revocation notifications.

If the "UserConsentRevocation" feature is supported by the EAS, this attribute shall be present in an HTTP POST request/response, and HTTP PUT request/response, and HTTP PATCH responses, and may be present in an HTTP PATCH request, if the revocation notification needs to be updated.

UserConsentRevocation

requestTestNotification

boolean

O

0..1

Set to true by Subscriber to request the EES to send a test notification as defined in clause 7.6. Set to false or omitted otherwise.

Notification_test_event

websockNotifConfig

WebsockNotifConfig

O

0..1

Configuration parameters to set up notification delivery over Websocket protocol as defined in clause 7.6.

Notification_websocket

suppFeat

SupportedFeatures

C

0..1

Used to negotiate the supported optional features of the API as described in clause 7.8.

This attribute shall be provided in the HTTP POST request to create a new subscription resource, if at least one feature is supported, and in the HTTP POST response of successful resource creation, if it was present in the associated HTTP POST request.

NOTE: Only one of UE Identifier (ueId), Internal group identifier (intGrpId), and External group identifier (extGrpId) shall be included.

eventReq

ReportingInformation

O

0..1

The reporting requirements of the location information event subscription to be updated.

expTime

DateTime

O

0..1

Indicates the proposed expiration time of the subscription.

notificationDestination

Uri

O

0..1

Updated URI where the location information notification should be delivered to.

revocationNotifUri

Uri

O

0..1

Contains the updated URI via which the EAS desires to receive user consent revocation notifications.

This attribute may be present if the "UserConsentRevocation" feature is supported by the EAS.

UserConsentRevocation

locGran

Accuracy

O

0..1

Updated format of the location information that the EAS supports.

locQos

LocationQoS

O

0..1

Updated location QoS, as specified in 3GPP TS 29.572 [11].

subId

string

M

1

String identifying the individual Location information subscription for which the location notification is delivered.

locEvs

array(LocationEvent)

M

1..N

List of notifications that include the location information of the UE(s).

ueId

Gpsi

M

1

Identifier of the UE for which the location information is reported.

locInf

LocationInfo

C

0..1

Actual Location information of the UE. (NOTE)

locInfPred

UeMobilityExposure

C

0..1

Predictive location information of the UE. (NOTE)

NOTE: Only one of "locInf" or "locInfPred" shall be included.

ueId

Gpsi

M

1

Identifier of the UE for which the location information is requested.

gran

Accuracy

O

0..1

Format in which the location information is requested by the EAS.

locQos

LocationQoS

O

0..1

Indicates the location quality of service of the requested location information.

suppFeat

SupportedFeatures

C

0..1

Used to negotiate the supported optional features of the API as described in clause 7.8.

This attribute shall be provided in the HTTP POST request to retrieve UE location information, if at least one feature is supported.

ueLocation

LocationInfo

M

1

Contains the requested UE location information.

suppFeat

SupportedFeatures

C

0..1

Used to negotiate the supported optional features of the API as described in clause 7.8.

This attribute shall be provided in the HTTP POST response for UE location information retrieval, if it was present in the associated HTTP POST request.

subscriptionId

string

M

1

Contains the identifier of the subscription to which the notification is related.

consentsRevoked

array(ConsentRevoked)

M

1..N

Indicates the revoked user consents.

ucPurpose

UcPurpose

M

1

Identifies the purpose of the revoked user consent.

ueId

Gpsi

C

0..1

Contains the identifiers(s) of the UE(s) for which user consent was revoked.

(NOTE)

externalId

ExternalId

C

0..1

Indicates the user(s) for which user consent was revoked.

(NOTE)

NOTE: One of the "ueId" or "externalId" attributes shall be present.

CONSENT_REVOCATION_NOT_SUPPORTED

403 Forbidden

Indicates that the request is rejected because user consent management and enforcement is not supported by the client.

USER_CONSENT_NOT_GRANTED

403 Forbidden

Indicates that the request is rejected because user consent is not granted.

1

Notification_test_event

Testing of notification connection is supported according to clause 7.6.

2

Notification_websocket

The delivery of notifications over Websocket is supported according to clause 7.6. This feature requires that the Notification_test_event feature is also supported.

3

UserConsentRevocation

This feature indicates the support of user consent revocation management and enforcement (e.g. stop data processing).