Provide location for call creation process

code/API_definitions/webrtc-call-handling.yaml

@@ -167,24 +167,6 @@ info:
     }
     ```
 
-    # Authorization and authentication
-
-    The "Camara Security and Interoperability Profile" provides details of how an
-    API consumer requests an access token. Please refer to Identity and Consent
-    Management (https://github.com/camaraproject/IdentityAndConsentManagement/)
-    for the released version of the profile.
-
-    The specific authorization flows to be used will be agreed upon during the
-    onboarding process, happening between the API consumer and the API provider,
-    taking into account the declared purpose for accessing the API, whilst also
-    being subject to the prevailing legal framework dictated by local legislation.
-
-    In cases where personal data is processed by the API and users can exercise
-    their rights through mechanisms such as opt-in and/or opt-out, the use of
-    three-legged access tokens is mandatory. This ensures that the API remains
-    in compliance with privacy regulations, upholding the principles of
-    transparency and user-centric privacy-by-design.
-
     # Additional CAMARA error responses
     The list of error codes in this API specification is not exhaustive.
     Therefore the API specification may not document some non-mandatory error
@@ -198,14 +180,49 @@ info:
     As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible
     error response if it is explicitly documented in the API.
 
+    # Located calls
+
+    As part of the extended, or contextual information of calls, a location can
+    be provided as part of the call information. A regular call **MAY** provide
+    an `originatorLocationDetails` object in order to help the receiver to
+    locate the geographic position of the device calling. In aim of security,
+    routing or any other use case provided by the network.
+
+    As each party can share its own location, there are two separated objects
+    `originatorLocationDetails` and `receiverLocationDetails`, both serving
+    the same purpose and implementing the `locationDetails` schema.
+
+    The `locationDetails` schema follows PIDF-LO concepts (3GPP TS 24.229,
+    RFC 4119, RFC 5139, RFC 5491) with either a circle or ellipsoid shape.
+
     # Emergency Calling
+
     - Introduces a new `callType` attribute with values `REGULAR` or `EMERGENCY`.
-    - When `callType` is `EMERGENCY`, the client **MAY** include `locationDetails`
-    describing the caller's location.
-    - `locationDetails` follows PIDF-LO concepts (3GPP TS 24.229, RFC 4119, RFC 5139,
+    - When `callType` is `EMERGENCY`, the client **MAY** include
+    `originatorLocationDetails` describing the caller's location.
+    - `originatorLocationDetails` implements the `locationDetails` schema.
+    This schema follows PIDF-LO concepts (3GPP TS 24.229, RFC 4119, RFC 5139,
     RFC 5491) with either a circle or ellipsoid shape.
     - If `callType` is omitted, it defaults to `REGULAR`.
 
+    # Authorization and authentication
+
+    The "Camara Security and Interoperability Profile" provides details of how an
+    API consumer requests an access token. Please refer to Identity and Consent
+    Management (https://github.com/camaraproject/IdentityAndConsentManagement/)
+    for the released version of the profile.
+
+    The specific authorization flows to be used will be agreed upon during the
+    onboarding process, happening between the API consumer and the API provider,
+    taking into account the declared purpose for accessing the API, whilst also
+    being subject to the prevailing legal framework dictated by local legislation.
+
+    In cases where personal data is processed by the API and users can exercise
+    their rights through mechanisms such as opt-in and/or opt-out, the use of
+    three-legged access tokens is mandatory. This ensures that the API remains
+    in compliance with privacy regulations, upholding the principles of
+    transparency and user-centric privacy-by-design.
+
   license:
     name: Apache 2.0
     url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
@@ -245,10 +262,12 @@ paths:
             schema:
               $ref: '#/components/schemas/MediaSessionInformation'
             examples:
-              Media session request:
-                $ref: '#/components/examples/exampleMediaSessionRequest'
+              RegularMediaSessionRequest:
+                $ref: '#/components/examples/exampleRegularMediaSessionRequest'
               EmergencyMediaSessionRequest:
                 $ref: '#/components/examples/exampleEmergencyMediaSessionRequest'
+              LocatedMediaSessionRequest:
+                $ref: '#/components/examples/exampleLocatedMediaSessionRequest'
       responses:
         '201':
           description: Created
@@ -498,7 +517,7 @@ components:
           enum:
             - REGULAR
             - EMERGENCY
-        locationDetails:
+        originatorLocationDetails:
           $ref: '#/components/schemas/LocationDetails'
     WrtcSDPDescriptor:
       type: object
@@ -586,11 +605,8 @@ components:
           description: 'The method used to obtain the location information.
 
             * **GPS:** Global Positioning System (highly accurate)
-
             * **DBH:** Device-Based Hybrid
-
             * **DBH_HELO:** Device-Based Hybrid using Apple Hybridized Emergency Location
-
             * **Other:** Other methods (e.g., landmarks, IP Based etc.)
 
             '
@@ -672,7 +688,8 @@ components:
           type: number
           description: Orientation of the ellipsoid in degrees.
   examples:
-    exampleMediaSessionRequest:
+    exampleRegularMediaSessionRequest:
+      summary: Regular call initiation with media information
       value:
         originatorAddress: tel:+17085852753
         originatorName: tel:+17085852753
@@ -783,7 +800,7 @@ components:
           type: offer
           sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n"
         callType: EMERGENCY
-        locationDetails:
+        originatorLocationDetails:
           shape: Circle
           coordinates:
             latitude: 47.6062
@@ -794,6 +811,27 @@ components:
             pdf: normal
             value: 92
           timestamp: '2025-10-06T19:31:25Z'
+    exampleLocatedMediaSessionRequest:
+      summary: Regular call initiation with location details
+      value:
+        originatorAddress: 'tel:+17085852753'
+        originatorName: Alice
+        receiverAddress: tel:+17085854000
+        receiverName: Bob
+        offer:
+          type: offer
+          sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:3108871805 1 udp 2122262783 2001:e0:410:243a:a344:cee7:7b39:bb1e 47510 typ host generation 0 network-id 3 network-cost 900\r\na=ice-ufrag:47Nx\r\na=ice-pwd:ln3CttOSkObcQ7A0tYO1LXqy\r\na=ice-options:trickle renomination\r\na=mid:audio\r\na=extmap:2 http://www.ietf.org/id/draft-holmer-rmcat-transport-wide-cc-extensions-01\r\na=sendrecv\r\na=rtcp-mux\r\na=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:ruAnBNYnTJqDVZAIJV59VpQ5DxGI6tMX9h9kkHSz\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n"
+        originatorLocationDetails:
+          shape: Circle
+          coordinates:
+            latitude: 47.5124
+            longitude: -122.4176
+            radius: 27
+          method: GPS
+          confidence:
+            pdf: normal
+            value: 97
+          timestamp: '2025-10-06T19:31:25Z'
   responses:
     Generic400:
       description: Bad Request

code/API_definitions/webrtc-events.yaml

@@ -142,6 +142,21 @@ info:
     a unique SessionId, to create a dedicated subscription and receive events
     about the session itself and its status progressing inside the network.
 
+    **Located calls**
+
+    The CAMARA WebRTC API provides an standardization way to locate caller
+    origin. If provided by the network, it helps to contextualize the calls
+    in aim of enhanced security, routing or any other use case. The located
+    calls include a `originatorLocationDetails` object on the `session-invitation`
+    event that could be parsed and used by the API consumer.
+
+    As each party can share its own location, there are two separated objects
+    `originatorLocationDetails` and `receiverLocationDetails`, both serving
+    the same purpose and implementing the `locationDetails` schema.
+
+    The `locationDetails` schema follows PIDF-LO concepts (3GPP TS 24.229,
+    RFC 4119, RFC 5139, RFC 5491) with either a circle or ellipsoid shape.
+
     ## 3. Subscription ends (subscription-ended)
 
     A `org.camaraproject.webrtc-events.v0.subscription-ended` event indicates that
@@ -265,6 +280,8 @@ paths:
                     examples:
                       NEW_SESSION_INCOMING (session-invitation):
                         $ref: "#/components/examples/NEW_SESSION_INCOMING"
+                      NEW_LOCATED_SESSION_INCOMING (session-invitation):
+                        $ref: "#/components/examples/NEW_LOCATED_SESSION_INCOMING"
                       SESSION_UPDATE (session-status):
                         $ref: "#/components/examples/SESSION_UPDATE"
                       REGISTRATION_EXPIRED (registration-ends):
@@ -891,6 +908,10 @@ components:
         sequenceNumber:
           type: integer
           description: The sequence number of the notification sent to client
+        originatorLocationDetails:
+          $ref: '#/components/schemas/LocationDetails'
+        receiverLocationDetails:
+          $ref: '#/components/schemas/LocationDetails'
 
     MediaSessionStatusUpdate:
       allOf:
@@ -1030,6 +1051,116 @@ components:
           description: The HTTP method to use for sending the message.
           enum:
             - POST
+    LocationDetails:
+      type: object
+      description: Details about the caller's location and related information. This
+        object adheres to 3GPP TS 24.229, RFC 4119, RFC 5139, and RFC 5491 for PIDF-LO
+        compatibility.
+      properties:
+        shape:
+          type: string
+          enum:
+            - Circle
+            - Ellipsoid
+          description: The shape representing the caller's location (Circle or Ellipsoid).
+        coordinates:
+          oneOf:
+            - $ref: '#/components/schemas/CircleCoordinates'
+            - $ref: '#/components/schemas/EllipsoidCoordinates'
+          description: The coordinates of the caller's location, specific to the chosen
+            shape.
+        method:
+          type: string
+          enum:
+            - GPS
+            - DBH
+            - DBH_HELO
+            - Other
+          description: 'The method used to obtain the location information.
+
+            * **GPS:** Global Positioning System (highly accurate)
+            * **DBH:** Device-Based Hybrid
+            * **DBH_HELO:** Device-Based Hybrid using Apple Hybridized Emergency Location
+            * **Other:** Other methods (e.g., landmarks, IP Based etc.)
+
+            '
+        confidence:
+          type: object
+          description: The confidence level of the location information.
+          properties:
+            pdf:
+              type: string
+              enum:
+                - normal
+                - uniform
+              description: The probability density function (PDF) associated with the
+                confidence value.
+            value:
+              type: number
+              minimum: 0
+              maximum: 100
+              description: The confidence value (percentage).
+        timestamp:
+          type: string
+          format: date-time
+          description: The timestamp (in ISO 8601 format) indicating when the location
+            information was Calculated. \nThis is crucial for emergency services to
+            assess the timeliness of the data. if not provided current timestamp will
+            be used by default"
+    CircleCoordinates:
+      type: object
+      required:
+        - latitude
+        - longitude
+        - radius
+      properties:
+        latitude:
+          type: number
+          format: float
+          description: Latitude of the center point in decimal degrees (WGS84).
+        longitude:
+          type: number
+          format: float
+          description: Longitude of the center point in decimal degrees (WGS84).
+        radius:
+          type: number
+          format: float
+          description: Radius of the circle in meters, indicating the uncertainty.
+    EllipsoidCoordinates:
+      type: object
+      required:
+        - latitude
+        - longitude
+        - zAxis
+        - semiMajorAxis
+        - semiMinorAxis
+        - verticalAxis
+        - orientation
+      properties:
+        latitude:
+          type: number
+          format: float
+          description: Latitude in the WGS 84 geocentric coordinate system.
+        longitude:
+          type: number
+          format: float
+          description: Longitude in the WGS 84 geocentric coordinate system.
+        zAxis:
+          type: number
+          format: float
+          description: Altitude (optional) in the WGS 84 geocentric coordinate system.
+        semiMajorAxis:
+          type: number
+          description: Length of the semi-major axis of the ellipsoid in meters.
+        semiMinorAxis:
+          type: number
+          description: Length of the semi-minor axis of the ellipsoid in meters.
+        verticalAxis:
+          type: number
+          description: Length of the vertical axis of the ellipsoid in meters.
+        orientation:
+          type: number
+          description: Orientation of the ellipsoid in degrees.
 
   responses:
     CreateSubscriptionBadRequest400:
@@ -1505,6 +1636,42 @@ components:
           mediaSessionId: "0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF"
           reason: "New subscriber incoming call"
           sequenceNumber: 1
+    NEW_LOCATED_SESSION_INCOMING:
+      description: |-
+        Example of located `session-invitation` event.
+
+        An extended example of `session-invitation` that includes location
+        details within the `LocationDetails` object
+      value:
+        id: "VzYQCOClM6Kc7Xmyq7mP58Jx"
+        source: https://notificationServer.opentelco.com
+        type: org.camaraproject.webrtc-events.v0.session-invitation
+        specversion: "1.0"
+        datacontenttype: application/json
+        time: 2024-11-05T05:40:23.682Z
+        data:
+          subscriptionId: "qs15-h556-rt89-1298"
+          originatorAddress: "tel:+11234567899"
+          originatorName: "Alice"
+          receiverAddress: "tel:+11234998765"
+          receiverName: "Bob"
+          status: "Initial"
+          offer:
+            sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0"
+          mediaSessionId: "0AEE1B58BAEEDA3EABA42B32EBB3DFE07E9CFF402EAF9EED8EF"
+          reason: "New subscriber incoming call"
+          sequenceNumber: 1
+          locationDetails:
+            shape: Circle
+            coordinates:
+              latitude: 47.6062
+              longitude: -122.3321
+              radius: 35
+            method: GPS
+            confidence:
+              pdf: normal
+              value: 92
+            timestamp: '2024-11-05T05:35:12.254Z'
     REGISTRATION_ENDS:
       description: |-
         Example of `registration-ends` events.