6.4 Namf_Location Service API

29.5183GPP5G SystemAccess and Mobility Management ServicesRelease 16Stage 3TS

6.4.1 API URI

The Namf_Location shall use the Namf_ Location API.

The API URI of the Namf_Location API shall be:

{apiRoot}/<apiName>/<apiVersion>/

The request URI used in HTTP requests from the NF service consumer towards the NF service producer shall have the Resource URI structure defined in clause 4.4.1 of 3GPP TS 29.501 [5], i.e.:

{apiRoot}/<apiName>/<apiVersion>/<apiSpecificResourceUriPart>

with the following components:

– The {apiRoot} shall be set as described in 3GPP TS 29.501 [5].

– The <apiName> shall be "namf-loc".

– The <apiVersion> shall be "v1".

– The <apiSpecificResourceUriPart> shall be set as described in clause 6.4.3.

6.4.2 Usage of HTTP

6.4.2.1 General

HTTP/2, as defined in IETF RFC 7540 [19], shall be used as specified in clause 5 of 3GPP TS 29.500 [4].

HTTP/2 shall be transported as specified in clause 5.3 of 3GPP TS 29.500 [4].

HTTP messages and bodies for the Namf_Location service shall comply with the OpenAPI [23] specification contained in Annex A.

6.4.2.2 HTTP standard headers

6.4.2.2.1 General

The usage of HTTP standard headers shall be supported as specified in clause 5.2.2 of 3GPP TS 29.500 [4].

6.4.2.2.2 Content type

The following content types shall be supported:

– JSON, as defined in IETF RFC 8259 [8], shall be used as content type of the HTTP bodies specified in the present specification as indicated in clause 5.4 of 3GPP TS 29.500 [4].

– The Problem Details JSON Object (IETF RFC 7807 [36]). The use of the Problem Details JSON object in a HTTP response body shall be signalled by the content type "application/problem+json".

6.4.2.3 HTTP custom headers

6.4.2.3.1 General

In this release of this specification, no custom headers specific to the Namf_Location service are defined. For 3GPP specific HTTP custom headers used across all service based interfaces, see clause 5.2.3 of 3GPP TS 29.500 [4].

6.4.3 Resources

6.4.3.1 Overview

Figure 6.4.3.1-1: Resource URI structure of the Namf_Location Service API

Table 6.4.3.1-1 provides an overview of the resources and applicable HTTP methods.

Table 6.4.3.1-1: Resources and methods overview

Resource name

Resource URI

HTTP method or custom operation

Description

Individual UE context

/provide-pos-info

provide-pos-info
(POST)

ProvidePositioningInfo

/provide-loc-info

provide-loc-info
(POST)

ProvideLocationInfo

/cancel-pos-info

cancel-pos-info
(POST)

CancelLocation

6.4.3.2 Resource: Individual UE Context

6.4.3.2.1 Description

This resource represents an individual ueContextId.

This resource is modelled with the Document resource archetype (see clause C.1 of 3GPP TS 29.501 [5]).

6.4.3.2.2 Resource Definition

Resource URI:{apiRoot}/namf-loc/<apiVersion>/{ueContextId}

This resource shall support the resource URI variables defined in table 6.4.3.2.2-1.

Table 6.4.3.2.2-1: Resource URI variables for this resource

Name

Data type

Definition

apiRoot

string

See clause 6.4.1

apiVersion

string

See clause 6.4.1.

ueContextId

string

Represents the Subscription Permanent Identifier (see 3GPP TS 23.501 [2] clause 5.9.2)
pattern: see pattern of type Supi in 3GPP TS 29.571 [6]

Or represents the Permanent Equipment Identifier (see 3GPP TS 23.501 [2] clause 5.9.3)

pattern: "(imei-[0-9]{15}|imeisv-[0-9]{16}|.+)"

6.4.3.2.3 Resource Standard Methods

There are no standard methods supported on this resource.

6.4.3.2.4 Resource Custom Operations
6.4.3.2.4.1 Overview

Table 6.4.3.2.4.1-1: Custom operations

Operation Name

Custom operaration URI

Mapped HTTP method

Description

provide-pos-info

/{ueContextId}/provide-pos-info

POST

Request the positioning information of the UE.

It is used for the ProvidePositioningInfo service operation.

provide-loc-info

/{ueContextId}/provide-loc-info

POST

Request the Network Provided Location Information of the UE.

cancel-pos-info

/{ueContextId}/cancel-pos-info

POST

Cancels periodic or triggered location for the UE.

6.4.3.2.4.2 Operation: provide-pos-info (POST)

6.4.3.2.4.2.1 Description

This ueContextId identifies the individual ueContext resource is composed by UE’s SUPI or PEI.

6.4.3.2.4.2.2 Operation Definition

This operation shall support the request data structures specified in table 6.4.3.2.4.2.2-1 and the response data structure and response codes specified in table 6.4.3.2.4.2.2-2.

Table 6.4.3.2.4.2.2-1: Data structures supported by the provide-pos-info operation Request Body

Data type

P

Cardinality

Description

RequestPosInfo

M

1

The information to request the positioning information of the UE.

Table 6.4.3.2.4.2.2-2: Data structures supported by the provide-pos-info operation Response Body

Data type

P

Cardinality

Response

codes

Description

ProvidePosInfo

M

1

200 OK

This case represents a successful query of the UE positioning information, the AMF returns the related information in the response.

n/a

204 No Content

Shall return 204 if no information is to be returned

RedirectResponse

O

0..1

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing a different URI, or the same URI if a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same AMF or AMF (service) set.

RedirectResponse

O

0..1

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing a different URI, or the same URI if a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same AMF or AMF (service) set.

ProblemDetails

O

0..1

403 Forbidden

The "cause" attribute may be used to indicate one of the following application errors:

– USER_UNKNOWN

– DETACHED_USER

– POSITIONING_DENIED

– UNSPECIFIED

See table 6.4.7.3-1 for the description of these errors.

ProblemDetails

O

0..1

500 Internal Server Error

The "cause" attribute may be used to indicate one of the following application errors:

– POSITIONING_FAILED

See table 6.1.7.3-1 for the description of these errors.

ProblemDetails

O

0..1

504 Gateway Timeout

The "cause" attribute may be used to indicate one of the following application errors:

– UNREACHABLE_USER

– PEER_NOT_RESPONDING

See table 6.4.7.3-1 for the description of this error.

Table 6.4.3.2.4.2.2-3: 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 on an alternative service instance within the same AMF or AMF (service) set.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

Table 6.4.3.2.4.2.2-4: 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 on an alternative service instance within the same AMF or AMF (service) set.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.4.3.2.4.3 Operation: provide-loc-info (POST)

6.4.3.2.4.3.1 Description

This ueContextId identifies the individual ueContext resource is composed by UE’s SUPI.

6.4.3.2.4.3.2 Operation Definition

This operation shall support the request data structures specified in table 6.4.3.2.4.3.2-1 and the response data structure and response codes specified in table 6.4.3.2.4.3.2-2.

Table 6.4.3.2.4.3.2-1: Data structures supported by the povideLocInfo operation Request Body

Data type

P

Cardinality

Description

RequestLocInfo

M

1

The information to request the NPLI of the UE.

Table 6.4.3.2.4.3.2-2: Data structures supported by the provide-loc-info operation Response Body

Data type

P

Cardinality

Response

codes

Description

ProvideLocInfo

M

1

200 OK

This case represents a successful query of the NPLI of the target UE, the AMF returns the related information in the response.

RedirectResponse

O

0..1

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing a different URI, or the same URI if a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same AMF or AMF (service) set.

RedirectResponse

O

0..1

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing a different URI, or the same URI if a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same AMF or AMF (service) set.

ProblemDetails

O

0..1

403 Forbidden

The "cause" attribute may be used to indicate one of the following application errors:

– UNSPECIFIED

See table 6.4.7.3-1 for the description of these errors.

ProblemDetails

O

0..1

404 Not Found

The "cause" attribute may be used to indicate one of the following application errors:

– CONTEXT NOT_FOUND

See table 6.4.7.3-1 for the description of these errors.

Table 6.4.3.2.4.3.2-3: 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 on an alternative service instance within the same AMF or AMF (service) set.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

Table 6.4.3.2.4.3.2-4: 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 on an alternative service instance within the same AMF or AMF (service) set.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.4.3.2.4.4 Operation: cancel-pos-info (POST)

6.4.3.2.4.4.1 Description

This ueContextId identifies the individual ueContext resource and is composed by UE’s SUPI.

6.4.3.2.4.4.2 Operation Definition

This operation shall support the request data structures specified in table 6.4.3.2.4.4.2-1 and the response data structure and response codes specified in table 6.4.3.2.4.4.2-2.

Table 6.4.3.2.4.4.2-1: Data structures supported by the cancel-pos-info operation Request Body

Data type

P

Cardinality

Description

CancelPosInfo

M

1

The information to identify the location session to be cancelled.

Table 6.4.3.2.4.4.2-2: Data structures supported by the cancel-pos-info operation Response Body

Data type

P

Cardinality

Response

codes

Description

n/a

204 No Content

This case represents successful cancellation of location.

RedirectResponse

O

0..1

307 Temporary Redirect

Temporary redirection. The response shall include a Location header field containing a different URI, or the same URI if a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same AMF or AMF (service) set.

RedirectResponse

O

0..1

308 Permanent Redirect

Permanent redirection. The response shall include a Location header field containing a different URI, or the same URI if a request is redirected to the same target resource via a different SCP. In the former case, the URI shall be an alternative URI of the resource located on an alternative service instance within the same AMF or AMF (service) set.

ProblemDetails

O

0..1

403 Forbidden

The "cause" attribute may be used to indicate one of the following application errors:

– USER_UNKNOWN

– LOCATION_SESSION_UNKNOWN

– UNSPECIFIED

See table 6.4.7.3-1 for the description of these errors.

ProblemDetails

O

0..1

504 Gateway Timeout

The "cause" attribute may be used to indicate one of the following application errors:

– UNREACHABLE_USER

– PEER_NOT_RESPONDING

See table 6.4.7.3-1 for the description of this error.

Table 6.4.3.2.4.4.2-3: 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 on an alternative service instance within the same AMF or AMF (service) set.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

Table 6.4.3.2.4.4.2-4: 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 on an alternative service instance within the same AMF or AMF (service) set.

Or the same URI, if a request is redirected to the same target resource via a different SCP.

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.4.4 Custom Operations without associated resources

There are no custom operations without associated resources supported on Namf_Location service.

6.4.5 Notifications

6.4.5.1 General

This clause provides the definition of the EventNotify notification of the Namf_Location service.

Table 6.4.5.1-1: Notifications overview

Notification

Callback URI

HTTP method or custom operation

Description

(service operation)

Event Notify

{locationNotificationUri}

POST

6.4.5.2 Event Notify

6.4.5.2.1 Description

This resource represents the callback reference of the NF Service Consumer (e.g. GMLC) to receive LCS event notify.

6.4.5.2.2 Notification Definition

Callback URI: {locationNotificationUri}

See clause 5.5.2.3.1 for the description of how the AMF obtains the Callback URI of the NF Service Consumer (e.g. GMLC).

6.4.5.2.3 Notification Standard Methods
6.4.5.2.3.1 POST

This method sends an LCS event notify to the NF Service Consumer.

This method shall support the request data structures specified in table 6.4.5.2.3.1-1 and the response data structures and response codes specified in table 6.4.5.2.3.1-2.

Table 6.4.5.2.3.1-1: Data structures supported by the POST Request Body

Data type

P

Cardinality

Description

NotifiedPosInfo

M

1

Representation of the LCS event notify.

Table 6.4.5.2.3.1-2: Data structures supported by the POST Response Body

Data type

P

Cardinality

Response

codes

Description

n/a

204 No Content

This case represents a successful notification of the LCS event.

RedirectResponse

O

0..1

307 Temporary Redirect

Temporary redirection. The NF service consumer shall generate a Location header field containing a URI pointing to the endpoint of another NF service consumer to which the notification should be sent.

If an SCP redirects the message to another SCP then the location header field shall contain the same URI or a different URI pointing to the endpoint of the NF service consumer to which the notification should be sent.

RedirectResponse

O

0..1

308 Permanent Redirect

Permanent redirection. The NF service consumer shall generate a Location header field containing a URI pointing to the endpoint of another NF service consumer to which the notification should be sent.

If an SCP redirects the message to another SCP then the location header field shall contain the same URI or a different URI pointing to the endpoint of the NF service consumer to which the notification should be sent.

Table 6.4.5.2.3.1-3: Headers supported by the 307 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

A URI pointing to the endpoint of the NF service consumer to which the notification should be sent

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

Table 6.4.5.2.3.1-4: Headers supported by the 308 Response Code on this resource

Name

Data type

P

Cardinality

Description

Location

string

M

1

A URI pointing to the endpoint of the NF service consumer to which the notification should be sent

3gpp-Sbi-Target-Nf-Id

string

O

0..1

Identifier of the target NF (service) instance ID towards which the request is redirected

6.4.6 Data Model

6.4.6.1 General

This clause specifies the application data model supported by the API.

Table 6.4.6.1-1 specifies the data types defined for the Namf_Location service based interface protocol.

Table 6.4.6.1-1: Namf_Location specific Data Types

Data type

Clause defined

Description

RequestPosInfo

6.4.6.2.2

Information within Provide Positioning Information Request

ProvidePosInfo

6.4.6.2.3

Information within Provide Positioning Information Response

NotifiedPosInfo

6.4.6.2.4

Information within EventNotify notification

RequestLocInfo

6.4.6.2.5

Information within Provide Location Information Request

ProvideLocInfo

6.4.6.2.6

Information within Provide Location Information Response

CancelPosInfo

6.4.6.2.7

Information within a Cancel Location Request

LocationType

6.4.6.3.3

Type of location measurement requested

LocationEvent

6.4.6.3.4

Type of events initiating location procedures

LocationPrivacyVerResult

6.4.6.3.5

The result of location privacy verification by UE

Table 6.4.6.1-2 specifies data types re-used by the Namf_Location service based interface protocol from other specifications, including a reference to their respective specifications and when needed, a short description of their use within the Namf_Location service based interface.

Table 6.4.6.1-2: Namf_Location re-used Data Types

Data type

Reference

Comments

Supi

3GPP TS 29.571 [6]

Subscription Permanent Identifier

Gpsi

3GPP TS 29.571 [6]

General Public Subscription Identifier

Pei

3GPP TS 29.571 [6]

Permanent Equipment Identifier

ExternalClientType

3GPP TS 29.572 [25]

LCS Client Type (Emergency, Lawful Interception …)

LocationQoS

3GPP TS 29.572 [25]

LCS QoS (accuracy, response time)

SupportedGADShapes

3GPP TS 29.572 [25]

LCS supported GAD shapes

GeographicArea

3GPP TS 29.572 [25]

Estimate of the location of the UE

AccuracyFulfilmentIndicator

3GPP TS 29.572 [25]

Requested accuracy was fulfilled or not

AgeOfLocationEstimate

3GPP TS 29.572 [25]

Age Of Location Estimate

PositioningMethodAndUsage

3GPP TS 29.572 [25]

Usage of each non-GANSS positioning method

VelocityEstimate

3GPP TS 29.572 [25]

Estimate of the velocity of the target UE

VelocityRequested

3GPP TS 29.572 [25]

Indication of the Velocity requirement

LcsPriority

3GPP TS 29.572 [25]

Priority of the LCS client

GnssPositioningMethodAndUsage

3GPP TS 29.572 [25]

Usage of each GANSS positioning method

CivicAddress

3GPP TS 29.572 [25]

Civic address

BarometricPressure

3GPP TS 29.572 [25]

Barometric Pressure

Altitude

3GPP TS 29.572 [25]

Altitude estimate of the UE

Ecgi

3GPP TS 29.571 [6]

UE EUTRAN cell information

Ncgi

3GPP TS 29.571 [6]

UE NR cell information

SupportedFeatures

3GPP TS 29.571 [6]

Supported Features

RatType

3GPP TS 29.571 [6]

RAT type

TimeZone

3GPP TS 29.571 [6]

Time Zone

DateTime

3GPP TS 29.571 [6]

Date and Time

UserLocation

3GPP TS 29.571 [6]

User Location

LcsServiceType

3GPP TS 29.572 [25]

The LCS service type

LdrType

3GPP TS 29.572 [25]

The type of LDR for deferred location

Uri

3GPP TS 29.571 [6]

URI

LdrReference

3GPP TS 29.572 [25]

LDR Reference Number for deferred location

PeriodicEventInfo

3GPP TS 29.572 [25]

Information for periodic event reporting

AreaEventInfo

3GPP TS 29.572 [25]

Information for area event reporting

MotionEventInfo

3GPP TS 29.572 [25]

Information for motion event reporting

ExternalClientIdentification

3GPP TS 29.515 [46]

External LCS client identification

NFInstanceId

3GPP TS 29.571 [6]

Identification of an NF or AF

CodeWord

3GPP TS 29.515 [46]

Codeword for a 5GC-MT-LR or deferred 5GC-MT-LR

LMFIdentification

3GPP TS 29.572 [25]

Identification of a serving LMF for periodic or triggered location

TerminationCause

3GPP TS 29.572 [25]

Termination cause for a deferred location

UePrivacyRequirements

3GPP TS 29.515 [46]

The location related privacy requirements on UE

DiameterIdentity

3GPP TS 29.571 [6]

Diameter Identity

ProblemDetails

3GPP TS 29.571 [6]

Detailed problems in failure case

RedirectResponse

3GPP TS 29.571 [6]

Response body of the redirect response message.

6.4.6.2 Structured data types

6.4.6.2.1 Introduction

Structured data types used in Namf_Location service are specified in this clause.

6.4.6.2.2 Type: RequestPosInfo

Table 6.4.6.2.2-1: Definition of type RequestPosInfo

Attribute name

Data type

P

Cardinality

Description

lcsClientType

ExternalClientType

M

1

This IE shall contain the type of LCS client (Emergency, Lawful Interception etc.,.) issuing the location request

lcsLocation

LocationType

M

1

This IE shall contain the type of location measurement requested, such as current location,current or last known location, deferred location, etc.

(NOTE 2)

supi

Supi

C

0..1

If the SUPI is available, this IE shall be present.

gpsi

Gpsi

C

0..1

If the GPSI is available, this IE shall be present.

priority

LcsPriority

O

0..1

If present, this IE shall contain the priority of the LCS client issuing the positioning request.

lcsQoS

LocationQoS

O

0..1

If present, this IE shall contain the quality of service requested, such as the accuracy of the positioning measurement and the response time of the positioning operation

velocityRequested

VelocityRequested

O

0..1

If present, this IE shall contain an indication of whether or not the Velocity of the target UE is requested.

lcsSupportedGADShapes

SupportedGADShapes

O

0..1

If present, this IE shall contain one GAD shape supported by the LCS client.

additionalSuppGADShapes

array(SupportedGADShapes)

C

1..N

Shall be absent if lcsSupportedGADShapes is absent.
Shall be present if the LCS client supports more than one GAD shape.

locationNotificationUri

Uri

O

0..1

The callback URI on which location change event notification is reported.

supportedFeatures

SupportedFeatures

C

0..1

This IE shall be present if at least one optional feature defined in clause 6.4.8 is supported.

oldGuami

Guami

C

0..1

This IE shall be present during an AMF planned removal procedure when the NF Service Consumer initiates a request towards the target AMF, for a UE associated to an AMF that is unavailable (see clause 5.21.2.2 of 3GPP TS 23.501 [2]).

pei

Pei

C

0..1

This IE shall be present if supi and gpsi are not available.

lcsServiceType

LcsServiceType

O

0..1

This IE contains the LCS service type for an external client.

(NOTE 1)

ldrType

LdrType

C

0..1

This IE contains the type of LDR for a deferred location request. This IE shall be present when lcsLocation is set to "DEFERRED_LOCATION".

hgmlcCallBackURI

Uri

C

0..1

This IE contrains the callback URI of the H-GMLC for a deferred location request. This IE shall be present when lcsLocation is set to "DEFERRED_LOCATION".

ldrReference

LdrReference

C

0..1

This IE contains the LDR Reference Number for a deferred location request This IE shall be present when lcsLocation is set to "DEFERRED_LOCATION".

periodicEventInfo

PeriodicEventInfo

C

0..1

This IE contains information for periodic event reporting for a deferred location request. This IE shall be present when ldrType is set to "PERIODIC".

areaEventInfo

AreaEventInfo

C

0..1

This IE contains information for area event reporting for a deferred location request. This IE shall be present when ldrType is set to "ENTERING_INTO_AREA", "LEAVING_FROM_AREA" or "BEING_INSIDE_AREA".

motionEventInfo

MotionEventInfo

C

0..1

This IE contains information for motion event reporting for a deferred location request. This IE shall be present when ldrType is set to "MOTION".

externalClientIdentification

ExternalClientIdentification

O

0..1

This IE provides the external LCS client identification (e.g. the name of the LCS client).

(NOTE 1)

afID

NfInstanceId

O

0..1

This IE provides the identification of an AF that initiated the location request.

(NOTE 1)

codeWord

CodeWord

O

0..1

This IE provides a codeword for a location request which is provided by an external Client or AF and is sent to and verified by a target UE as part of privacy verification.

(NOTE 1)

uePrivacyRequirements

UePrivacyRequirements

O

0..1

If present, the IE provides the indication of location related notification or verification for the target UE, the indication of codeword check in UE

NOTE 1: At least one of these IEs should be present when uePrivacyCallSessionUnrelatedClass indicates notification and/or verification for the target UE.

NOTE 2: If the lcsLocation IE is set to value "NOTIFICATION_VERIFICATION_ONLY", then the lcsServiceAuthInfo attribute in the uePrivacyRequirements IE, if present, shall be set to either "NOTIFICATION_ONLY" or "NOTIFICATION_AND_VERIFICATION_ONLY".

6.4.6.2.3 Type: ProvidePosInfo

Table 6.4.6.2.3-1: Definition of type ProvidePosInfo

Attribute name

Data type

P

Cardinality

Description

locationEstimate

GeographicArea

O

0..1

If present, this IE shall contain an estimate of the location of the UE in universal coordinates and the accuracy of the estimate.

accuracyFulfilmentIndicator

AccuracyFulfilmentIndicator

O

0..1

If present, this IE shall contain an indication of whether the requested accuracy (as indicated in the LcsQoS in the request message) was fulfilled or not.

ageOfLocationEstimate

AgeOfLocationEstimate

O

0..1

If present, this IE shall contain an indication of how long ago the location estimate was obtained.

velocityEstimate

VelocityEstimate

O

0..1

If present, this IE shall contain an estimate of the velocity of the target UE, composed by horizontal speed, vertical speed, and their respective uncertainty.

positioningDataList

array(PositioningMethodAndUsage)

O

0..9

If present, this IE shall indicate the usage of each non- GANSS positioning method that was attempted to determine the location estimate, either successfully or unsuccessfully.

gnssPositioningDataList

array(GnssPositioningMethodAndUsage)

O

0..9

If present, this IE shall indicate the usage of each GANSS positioning method that was attempted to determine the location estimate, either successfully or unsuccessfully.

ecgi

Ecgi

O

0..1

If present, this IE shall contain the current EUTRAN cell location of the target UE as delivered by the 5G-AN.

ncgi

Ncgi

O

0..1

If present, this IE shall contain the current NR cell location of the target UE as delivered by the 5G-AN.

targetServingNode

NfInstanceId

O

0..1

If present, this IE shall contain the address of the target side serving node for intra-5GS handover of an IMS Emergency Call.

targetMmeName

DiameterIdentity

C

0..1

This IE shall be present for handover of IMS emergency call to EPS, i.e. the target node is an MME.

When present, this IE shall indicate the Diameter host name of the target MME.

targetMmeRealm

DiameterIdentity

C

0..1

This IE shall be present for handover of IMS emergency call to EPS, i.e. the target node is an MME.

When present, this IE shall indicate the Diameter realm of the target MME.

utranSrvccInd

boolean

C

0..1

This IE shall be present with value "true" for 5G-SRVCC to 3GPP UTRAN of IMS emergency call, i.e. target node is an MSC.

When present, this IE shall be set for the following value:

– true: IMS emergency call handover to UTRAN

– false: No IMS emergency call handover to UTRAN

civicAddress

CivicAddress

O

0..1

If present, this IE contains a location estimate for the target UE expressed as a Civic address.

barometricPressure

BarometricPressure

O

0..1

If present, this IE contains the barometric pressure measurement as reported by the target UE.

altitude

Altitude

O

0..1

If present, this IE indicates the altitude of the positioning estimate.

supportedFeatures

SupportedFeatures

C

0..1

This IE shall be present if at least one optional feature defined in clause 6.4.8 is supported.

servingLMFIdentification

LMFIdentification

O

0..1

If present, this IE contains the identification of a serving LMF for periodic or triggered location

locationPrivacyVerResult

LocationPrivacyVerResult

O

0..1

If present, this IE contains the result of location privacy verification by UE (NOTE)

NOTE: The IE may be included to indicate the result of location privacy verification by UE to (H)GMLC when a location request with notification and privacy verification only indication is sent to the serving AMF by (H)GMLC during location request procedure.

6.4.6.2.4 Type: NotifiedPosInfo

Table 6.4.6.2.4-1: Definition of type NotifiedPosInfo

Attribute name

Data type

P

Cardinality

Description

locationEvent

LocationEvent

M

1

This IE shall contain the type of event that caused the location procedure to be initiated.

supi

Supi

C

0..1

This IE shall contain the SUPI if available (see NOTE 1).

gpsi

Gpsi

C

0..1

This IE shall contain the GPSI if available (see NOTE 1).

pei

Pei

C

0..1

This IE shall contain the PEI if available (see NOTE 1).

locationEstimate

GeographicArea

O

0..1

If present, this IE shall contain an estimate of the location of the UE in universal coordinates and the accuracy of the estimate.

ageOfLocationEstimate

AgeOfLocationEstimate

O

0..1

If present, this IE shall contain an indication of how long ago the location estimate was obtained.

velocityEstimate

VelocityEstimate

O

0..1

If present, this IE shall contain an estimate of the velocity of the target UE, composed by horizontal speed, vertical speed, and their respective uncertainty.

positioningDataList

array(PositioningMethodAndUsage)

O

0..9

If present, this IE shall indicate the usage of each non-GANSS positioning method that was attempted to determine the location estimate, either successfully or unsuccessfully.

gnssPositioningDataList

array(GnssPositioningMethodAndUsage)

O

0..9

If present, this IE shall indicate the usage of each GANSS positioning method that was attempted to determine the location estimate, either successfully or unsuccessfully.

ecgi

Ecgi

O

0..1

If present, this IE shall contain the current EUTRAN cell location of the target UE as delivered by the 5G-AN.

ncgi

Ncgi

O

0..1

If present, this IE shall contain the current NR cell location of the target UE as delivered by the 5G-AN.

servingNode

NfInstanceId

O

0..1

If present, this IE shall contain the address of the serving node. For intra-5GS handover of an IMS Emergency Call, this IE shall contain the address of the target side serving node. For mobility of a UE with periodic or triggered location, this IE shall contain the address of the new serving node, if available.

targetMmeName

DiameterIdentity

C

0..1

This IE shall be present for handover of IMS emergency call to EPS, i.e. the target node is an MME.

When present, this IE shall indicate the Diameter host name of the target MME.

targetMmeRealm

DiameterIdentity

C

0..1

This IE shall be present for handover of IMS emergency call to EPS, i.e. the target node is an MME.

When present, this IE shall indicate the Diameter realm of the target MME.

utranSrvccInd

boolean

C

0..1

This IE shall be present with value "true" for 5G-SRVCC to 3GPP UTRAN of IMS emergency call, i.e. target node is an MSC.

When present, this IE shall be set for the following value:

– true: IMS emergency call handover to UTRAN

– false: No IMS emergency call handover to UTRAN

civicAddress

CivicAddress

O

0..1

If present, this IE contains a location estimate for the target UE expressed as a Civic address.

barometricPressure

BarometricPressure

O

0..1

If present, this IE contains the barometric pressure measurement as reported by the target UE.

altitude

Altitude

O

0..1

If present, this IE indicates the altitude of the positioning estimate.

hgmlcCallBackURI

Uri

C

0..1

This IE contains the callback URI of the H-GMLC

This IE shall be included for a locationEvent related to deferred location when the consumer NF is not the H-GMLC.

ldrReference

LdrReference

C

0..1

This IE contains an LDR Reference.

This IE shall be included for a locationEvent related to deferred location.

servingLMFIdentification

LMFIdentification

C

0..1

This IE contains the identification of a serving LMF and shall be included for a locationEvent related to deferred location with periodic or triggered location if a serving LMF is used.

terminationCause

TerminationCause

C

0..1

This IE indicates a reason for termination and shall be included for a locationEvent related to deferred location if deferred location has been terminated.

NOTE 1: At least one of these IEs shall be present in the message.

6.4.6.2.5 Type: RequestLocInfo

Table 6.4.6.2.5-1: Definition of type RequestLocInfo

Attribute name

Data type

P

Cardinality

Description

req5gsLoc

boolean

C

0..1

This IE shall be present and set to "true", if 5GS location information is requested in NPLI.

When present, the IE shall be set as following:

– true: the location of the UE is requested

– false (default): the location of the UE is not requested

reqCurrentLoc

boolean

C

0..1

This IE may be present if 5GS location information is requested in NPLI.

When present, the IE shall be set as following:

– true: the current location of the UE is requested

– false (default): the current location of the UE is not requested

reqRatType

boolean

C

0..1

This IE shall be present and set to "true", if the RAT Type of the UE is requested in NPLI.

When present, the IE shall be set as following:

– true: the RAT type of the UE is requested

– false (default): the RAT type of the UE is not requested

reqTimeZone

boolean

C

0..1

This IE shall be present and set to "true, if the local timezone of the UE is requested in NPLI.

When present, the IE shall be set as following:

– true: the local timezone of the UE is requested

– false (default): the local timezone of the UE is not requested.

supportedFeatures

SupportedFeatures

C

0..1

This IE shall be present if at least one optional feature defined in clause 6.4.8 is supported.

oldGuami

Guami

C

0..1

This IE shall be present during an AMF planned removal procedure when the NF Service Consumer initiates a request towards the target AMF, for a UE associated to an AMF that is unavailable (see clause 5.21.2.2 of 3GPP TS 23.501 [2]).

6.4.6.2.6 Type: ProvideLocInfo

Table 6.4.6.2.6-1: Definition of type ProvideLocInfo

Attribute name

Data type

P

Cardinality

Description

currentLoc

boolean

C

0..1

This IE shall be present, if the 5GS location information is requested by the NF Service consumer.

When present, this IE shall be set as following:

– true: the current location of the UE is returned

– false: the last known location of the UE is returned.

location

UserLocation

O

0..1

If present, this IE shall contain the location information of the UE.

This IE shall convey exactly one of the following:
– E-UTRA user location
– NR user location

– Non-3GPP access user location.

If the additionalLocation IE is present, this IE shall contain either an E-UTRA user location or NR user location.

additionalLocation

UserLocation

O

0..1

This IE shall be present if the "location IE" is present and the AMF reports both a 3GPP user location and a non-3GPP access user location.

When present, this IE shall convey the non-3GPP access user location.

geoInfo

GeographicArea

O

0..1

If present, this IE shall contain the geographical information of the UE (see NOTE 1).

locationAge

AgeOfLocationEstimate

O

0..1

If present, this IE shall contain the age of the location information (see NOTE 2).

ratType

RatType

O

0..1

If present, this IE shall contain the current RAT type of the UE.

timezone

TimeZone

O

0..1

If present, this IE shall contain the local time zone of the UE.

supportedFeatures

SupportedFeatures

C

0..1

This IE shall be present if at least one optional feature defined in clause 6.4.8 is supported.

NOTE 1: If geographical information is returned by the AMF, it shall be encoded in the "geoInfo" attribute and the "geographicalInformation" attribute within the "location" attribute shall not be used.

NOTE 2: If age of location estimate is returned by the AMF, it may be provided either in the "locationAge" attribute or in the "ageOfLocationInformation" attribute within the "location" attribute.

6.4.6.2.7 Type: CancelPosInfo

Table 6.4.6.2.7-1: Definition of type CancelPosInfo

Attribute name

Data type

P

Cardinality

Description

supi

Supi

M

1

SUPI

hgmlcCallBackURI

Uri

M

1

Callback URI of the H-GMLC

ldrReference

LdrReference

M

1

LDR Reference

servingLMFIdentification

LMFIdentification

C

0..1

Serving LMF identification. This IE shall be included if available.

supportedFeatures

SupportedFeatures

C

0..1

This IE shall be present if at least one optional feature defined in clause 6.4.8 is supported.

6.4.6.3 Simple data types and enumerations

6.4.6.3.1 Introduction

This clause defines simple data types and enumerations that can be referenced from data structures defined in the previous clauses.

6.4.6.3.2 Simple data types

The simple data types defined in table 6.4.6.3.2-1 shall be supported.

Table 6.4.6.3.2-1: Simple data types

Type Name

Type Definition

Description

6.4.6.3.3 Enumeration: LocationType

The enumeration LocationType represents the type of location measurement requested.

Table 6.4.6.3.3-1: Enumeration LocationType

Enumeration value

Description

"CURRENT_LOCATION"

This value indicates that the current location of the target UE is required.

"CURRENT_OR_LAST_KNOWN_LOCATION"

This value indicates that the current location or last known location of the target UE is required.

"NOTIFICATION_VERIFICATION_ONLY"

This value indicates that notification or verification of location by the target UE is required but a location estimate shall not be obtained.

"DEFERRED_LOCATION"

Deferred Location Request

6.4.6.3.4 Enumeration: LocationEvent

The enumeration LocationEvent represents the type of events initiating location procedures.

Table 6.4.6.3.4-1: Enumeration LocationEvent

Enumeration value

Description

"EMERGENCY_CALL_ORIGINATION"

Emergency session initiation

"EMERGENCY_CALL_RELEASE"

Emergency session termination

"EMERGENCY_CALL_HANDOVER"

Handover of an Emergency session

"ACTIVATION_OF_DEFERRED_LOCATION"

Confirmation of activation of periodic or triggered location in the target UE

"UE_MOBILITY_FOR_DEFERRED_LOCATION"

Mobility of the target UE to a different NF

"CANCELLATION_OF_DEFERRED_LOCATION"

Cancellation of a deferred location request

6.4.6.3.5 Enumeration: LocationPrivacyVerResult

The enumeration LocationPrivacyVerResult represents the type of the result of location privacy verification by UE.

Table 6.4.6.3.5-1: Enumeration LocationPrivacyVerResult

Enumeration value

Description

"LOCATION_ALLOWED"

Location is allowed by UE

"LOCATION_NOT_ALLOWED"

Location is not allowed by UE

"RESPONSE_TIME_OUT"

UE response times out

6.4.7 Error Handling

6.4.7.1 General

HTTP error handling shall be supported as specified in clause 5.2.4 of 3GPP TS 29.500 [4].

6.4.7.2 Protocol Errors

Protocol Error Handling shall be supported as specified in clause 5.2.7 of 3GPP TS 29.500 [4].

6.4.7.3 Application Errors

The common application errors defined in the Table 5.2.7.2-1 in 3GPP TS 29.501 [5] may also be used for the Namf_Location service, and the following application errors listed in Table 6.4.7.3-1 are specific for the Namf_Location service.

Table 6.4.7.3-1: Application errors

Application Error

HTTP status code

Description

USER_UNKNOWN

403 Forbidden

The user is unknown.

DETACHED_USER

403 Forbidden

The user is detached in the AMF.

POSITIONING_DENIED

403 Forbidden

The positioning procedure was denied.

UNSPECIFIED

403 Forbidden

The request is rejected due to unspecified reasons.

LOCATION_SESSION_UNKNOWN

403 Forbidden

The location session is unknown.

CONTEXT_NOT_FOUND

404 Not Found

The requested UE Context does not exist in the AMF.

POSITIONING_FAILED

500 Internal Server Error

The positioning procedure failed.

UNREACHABLE_USER

504 Gateway Timeout

The user could not be reached in order to perform positioning procedure.

PEER_NOT_RESPONDING

504 Gateway Timeout

No response is received from a remote peer, e.g. from the LMF.

6.4.8 Feature Negotiation

The feature negotiation mechanism specified in clause 6.6 of 3GPP TS 29.500 [4] shall be used to negotiate the optional features applicable between the AMF and the NF Service Consumer, for the Namf_Location service, if any.

The NF Service Consumer shall indicate the optional features it supports for the Namf_Location service, if any, by including the supportedFeatures attribute in payload of the HTTP Request Message for following service operations:

– ProvidePositioningInfo, as specified in clause 5.5.2.2;

– ProvideLocationInfo, as specified in clause 5.5.2.4;

– CancelLocation, as specified in clause 5.5.2.5

The AMF shall determine the supported features for the service operations as specified in clause 6.6 of 3GPP TS 29.500 [4] and shall indicate the supported features by including the supportedFeatures attribute in payload of the HTTP response for the service operation.

The syntax of the supportedFeatures attribute is defined in clause 5.2.2 of 3GPP TS 29.571 [6].

The following features are defined for the Namf_Location service.

Table 6.1.8-1: Features of supportedFeatures attribute used by Namf_Location service

Feature Number

Feature

M/O

Description

1

ES3XX

M

Extended Support of HTTP 307/308 redirection

An NF Service Consumer (e.g. GMLC) that supports this feature shall support handling of HTTP 307/308 redirection for any service operation of the Namf_Location service. An NF Service Consumer that does not support this feature does only support HTTP redirection as specified for 3GPP Release  15.

Feature number: The order number of the feature within the supportedFeatures attribute (starting with 1).

Feature: A short name that can be used to refer to the bit and to the feature.

M/O: Defines if the implementation of the feature is mandatory ("M") or optional ("O").

Description: A clear textual description of the feature.

6.4.9 Security

As indicated in 3GPP TS 33.501 [27], the access to the Namf_Location API may be authorized by means of the OAuth2 protocol (see IETF RFC 6749 [28]), using the "Client Credentials" authorization grant, where the NRF (see 3GPP TS 29.510 [29]) plays the role of the authorization server.

If Oauth2 authorization is used, an NF Service Consumer, prior to consuming services offered by the Namf_Location API, shall obtain a "token" from the authorization server, by invoking the Access Token Request service, as described in 3GPP TS 29.510 [29], clause 5.4.2.2.

NOTE: When multiple NRFs are deployed in a network, the NRF used as authorization server is the same NRF that the NF Service Consumer used for discovering the Namf_Location service.

The Namf_Location API defines scopes for OAuth2 authorization as specified in 3GPP TS 33.501 [27]; it defines a single scope consisting on the name of the service (i.e., "namf-loc"), and it does not define any additional scopes at resource or operation level.

6.4.10 HTTP redirection

An HTTP request may be redirected to a different AMF service instance, within the same AMF or a different AMF of an AMF set, e.g. when an AMF service instance is part of an AMF (service) set or when using indirect communications (see 3GPP TS 29.500 [4]). See the ES3XX feature in clause 6.4.8.

An SCP that reselects a different AMF producer instance will return the NF Instance ID of the new AMF producer instance in the 3gpp-Sbi-Producer-Id header, as specified in clause 6.10.3.4 of 3GPP TS 29.500 [4].

If an AMF within an AMF set redirects a service request to a different AMF of the set using an 307 Temporary Redirect or 308 Permanent Redirect status code, the identity of the new AMF towards which the service request is redirected shall be indicated in the 3gpp-Sbi-Target-Nf-Id header of the 307 Temporary Redirect or 308 Permanent Redirect response as specified in clause 6.10.9.1 of 3GPP TS 29.500 [4].

Annex A (normative):
OpenAPI specification