6.4 Namf_Location Service API
29.5183GPP5G SystemAccess and Mobility Management ServicesRelease 18Stage 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 |
ProvidePositioningInfo |
/provide-loc-info |
provide-loc-info |
ProvideLocationInfo |
|
/cancel-pos-info |
cancel-pos-info |
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) 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 (POST) 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 (POST) 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. |
NOTE: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply, with response body containing an object of ProblemDetails data type (see clause 5.2.7 of 3GPP TS 29.500 [4]). |
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 or PEI.
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 (POST) 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 (POST) 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. |
NOTE: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply, with response body containing an object of ProblemDetails data type (see clause 5.2.7 of 3GPP TS 29.500 [4]). |
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 or PEI.
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 (POST) 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 (POST) 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. |
NOTE: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply, with response body containing an object of ProblemDetails data type (see clause 5.2.7 of 3GPP TS 29.500 [4]). |
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. |
NOTE: The mandatory HTTP error status code for the POST method listed in Table 5.2.7.1-1 of 3GPP TS 29.500 [4] also apply, with response body containing an object of ProblemDetails data type (see clause 5.2.7 of 3GPP TS 29.500 [4]). |
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 |
Data within Provide Positioning Information Request |
ProvidePosInfo |
6.4.6.2.3 |
Data within Provide Positioning Information Response |
NotifiedPosInfo |
6.4.6.2.4 |
Data within EventNotify notification |
RequestLocInfo |
6.4.6.2.5 |
Data within Provide Location Information Request |
ProvideLocInfo |
6.4.6.2.6 |
Data within Provide Location Information Response |
CancelPosInfo |
6.4.6.2.7 |
Data 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 |
LocalArea |
3GPP TS 29.572 [25] |
Local area specified by different shape |
MinorLocationQoS |
3GPP TS 29.572 [25] |
Minor Location QoS |
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. |
E164Number |
3GPP TS 29.503 [35] |
The E.164 number. |
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. Multiple QoS Class (lcsQosClass sets to "MULTIPLE_QOS") shall only be used when AMF support MUTIQOS feature. |
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. |
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 |
scheduledLocTime |
DateTime |
O |
0..1 |
If present, the IE provides the scheduled time that the UE needs to be located. |
reliableLocReq |
boolean |
C |
0..1 |
This IE shall be included with the value "true" to indicate that reliable UE location information is required, as specified in 3GPP TS 33.256 [57] clause 5.3.2. When present, this IE shall be set as following: – true: the reliable UE location information is required – false (default): the reliable UE location information is not required |
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 |
Applicability |
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. |
|
localLocationEstimate |
LocalArea |
O |
0..1 |
When present, this IE shall indicate a local area in renference system. |
|
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. |
|
timestampOfLocationEstimate |
DateTime |
O |
0..1 |
When present, this IE shall indicate the estimated UTC time when the location estimate corresponded to the UE location (i.e. when the location estimate and the actual UE location was the same). |
|
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) |
|
achievedQos |
MinorLocationQoS |
C |
0..1 |
When present, this IE shall contain the achieved Location QoS Accuracy of the estimated location. This IE shall be present if received from LMF. |
MUTIQOS |
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 |
Applicability |
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. |
|
localLocationEstimate |
LocalArea |
O |
0..1 |
When present, this IE shall indicate a local area in renference system. |
|
ageOfLocationEstimate |
AgeOfLocationEstimate |
O |
0..1 |
If present, this IE shall contain an indication of how long ago the location estimate was obtained. |
|
timestampOfLocationEstimate |
DateTime |
O |
0..1 |
When present, this IE shall indicate the estimated UTC time when the location estimate corresponded to the UE location (i.e. when the location estimate and the actual UE location was the same). |
|
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. |
|
achievedQos |
MinorLocationQoS |
O |
0..1 |
When present, this IE shall contain the achieved Location QoS Accuracy of the estimated location. This IE shall be present if received from LMF. |
MUTIQOS |
mscServerId |
E164Number |
O |
0..1 |
This IE may be sent from AMF to GMLC, during a 5G-SRVCC handover from NG-RAN to UTRAN procedure. When present, it shall contain the international E.164 number of the MSC Server selected by the MME_SRVCC. |
|
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: – 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 (i.e. it is in RM-DEREGISTERED state) 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. |
2 |
MUTIQOS |
O |
Support of Multiple Location QoSes. This feature bit indicates whether the AMF support that more than one Location QoSes during consuming location service are required. |
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].