WARNING! Gitlab maintenance operation scheduled for Thursday, 18 June between 19:00 and 20:00 (CET). During this time window, short service interruptions (less than 5 minutes) may occur. Thank you in advance for your understanding.
> _All endpoints specified in v1 will be included in the MEC Sandbox as part of STF587. <br>v2 endpoints will be considered for Milestone D, depending availability in Forge and remaining STF587 effort. No change in scenario specification since Milestone A._
> _Updated by STF599_
This section describes how MEC013 has been integrated with the MEC Sandbox.
This section describes how MEC013 operates within the MEC Sandbox. All query endpoints and subscriptons with thier notifications are supported.
## MEC013 v1.1.1 - (available on Forge)
## MEC013 v2.1.1 - (published, available on forge)
| [/zones](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/mec/gs013-location-api/raw/master/LocationAPI.yaml#/operations/zones/zonesGet) | Discover the layout of the network – # of zones and their id's. <br><br>List of Zones: zone id with number of access points and users in a zone. | As a user, I use this call to learn the number of zones and their id's. <br><br> I can use the zone information to learn more information about the network. <br><br>**If I know nothing about the network, this end-point is a good API to first learn how the network is organized in zones, how many access points are in a zone, and where concentrations (#) of users may be.**
| [/zones/{zoneId}](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/mec/gs013-location-api/raw/master/LocationAPI.yaml#/operations/zones/zonesGetById)| Discover the Number of access points and users in a zone | Returns same data as /zones without an id. |
| [/zones/{zoneId}/accessPoints](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/mec/gs013-location-api/raw/master/LocationAPI.yaml#/operations/zones/zonesByIdGetAps)| Discover layout of points of access within a zone. <br><br> List of Access Points - assessPoint data: <br> - Access Point Id <br>- Geo-location: latitude, longitude <br>- Connection type <br> - Operation status <br> - # Users on the access point <br> - interest realm | As a user, I use this call to learn about points of access in the network, needing to reference by specific zones. <br><br>**This is a point to first learn details of Access Points, for example their location and number of connected users.** |
| [/zones/{zoneId}<br> /accessPoints/{accessPointId}](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/mec/gs013-location-api/raw/master/LocationAPI.yaml#/operations/zones/zonesByIdGetApsById) | accessPoint data for a single PoA | |
| [/users](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/mec/gs013-location-api/raw/master/LocationAPI.yaml#/operations/users/usersGet) ?zoneId=<...>| Input = zoneID, optional accessPointId <br><br> Discover information of users within a zone. <br><br> List of users in the zone (or PoA), including: <br> - address <br>- connected accessPointId <br>- connected zoneId | As a user, I use this call to find users (devices) and their identifiers (addresses). <br><br>**This is a point to first learn of a user, for example their address (i.e. id).** |
| [/users/{userId}](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/mec/gs013-location-api/raw/master/LocationAPI.yaml#/operations/users/usersGetById) | Input == userId (address) <br><br> Returns: <br>- address (same as input) <br>- accessPointId <br>- zoneId <br>- Geo-location: latitude, longitude | As a user after I know a user id (address), I use this call to find a users status: connected access point, connected zone, and geo-location. <br><br>**This is a query to first learn a user's geo-location.** |
| [/subscriptions/zonalTraffic](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/mec/gs013-location-api/raw/master/LocationAPI.yaml#/operations/subscriptions/zonalTrafficSubGet) | Subscription related to changes for a zone: users (devices) entering zone, exiting zone, transition across access points within a zone. <br><br> Input = zoneId; interestRealm; userEventCriteria; duration | Notification == Zonal Presence Notification <br><br> As a Sandbox User or ME App, I use this notification to monitor changes in a zone. |
| [/subscriptions/userTracking](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/mec/gs013-location-api/raw/master/LocationAPI.yaml#/operations/subscriptions/userTrackingSubGet) | Subscription related to changes of a specific user: zone enter, zone exit, transition across points of access. <br><br> Input = address (device id), userEventCriteria | Notification == Zonal Presence Notification <br><br> As a Sandbox User or ME App, I use this notification to track location changes for a specific user (or device). |
| [/subscriptions/zonalStatus](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/mec/gs013-location-api/raw/master/LocationAPI.yaml#/operations/subscriptions/zoneStatusGet) | Subscription related to changes in zone status: # of users in a zone, # of users per AP in a zone, etc. <br><br> Input = zoneId; numberOfUsersZoneThreshold; numberOfUsersAPThreshold | Notification == Zonal Status Notification <br><br> As a Sandbox User or ME App, I use this notification to monitor changes in a zone. |
| [/queries/distance](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/operations/location/distanceGET)<br><br>*New STF599* | Discover the distance between a user (i.e. a terminal device or UE) and a geo-location (latitude and longitude) or the distance between two users (i.e. terminal devices). <br><br> Query input: <ul><li> Two UE addresses == returns distance between them </li><li> UE address and geo-location (latitude and longitude) == returns distance from UE to the geo-location </li></ul> | As a MEC Sandbox user, I use this endpoint to determine the distance between two terminals in the MEC Sandbox or between a terminal and a specific geo-location. <br><br> I need to know the address of the terminal(s) (i.e. IP address id), which I can learn from other Location Service endpoints (e.g., /queries/users) or via the Sandbox GUI by clicking on a terminal icon. |
| [/queries/users](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/usersGET) | Discover information regarding users (i.e. terminal devices) in the MEC System. <br><br> Input parameters allow filtering of returned query information, including: <ul><li> List of zones (zoneId) </li><li> List of access points (accessPointId) </li><li> List of terminals (UE address) </li></ul><br><br> Returns user / terminal information including: <ul><li> address (i.e. IP address id) </li><li> connected access point (accessPointId) </li><li> connected zone (zoneId) </li><li> geo-location info (latitude and longitude) </li></ul> | As a MEC Sandbox user, I use this endpoint to find users (terminal devices), their identifiers (addresses), their connected point of access (PoA), and their location. <br><br>**This is an endpoint to first learn of a user, for example discovery their address (i.e. id).** |
| [/queries/zones](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/zonesGET) | Discover the layout of the network, such as the # of zones and their id's. <br><br>Returns a List of ZoneInfo with for each zone: zone id, number of access points, and number of connected users in a zone. | As a MEC Sandbox user, I use this call to learn the number of zones and their id's. <br><br> I can use the zone information to learn more information about the network. <br><br>**If I know nothing about the network, this endpoint is a good API to first learn how the network is organized in zones, how many access points are in a zone, and where concentrations (#) of user devices may be.**
| [/queries/zones/{zoneId}](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/zonesGetById)| Discover zone information for a single zone, based on its zoneId. <br><br>Returns ZoneInfo with for the requested zone: zone id, number of access points, and number of connected users in the zone. | Same data as /queries/zones, but for a single zone. |
| [/queries/zones/{zoneId}/accessPoints](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/apGET)| Discover the layout for the Points of Access within a zone. <br><br> Returns a List of Access Points with assessPointInfo: <ul><li> Access Point Id </li><li> Geo-location (latitude, longitude) </li><li> Connection type </li><li> Operation status </li><li> # of users connected to the access point </li><li> interest realm </li></ul> | As a user, I use this call to learn about points of access in the network, reference by specific zones. <br><br>**This is an endpoint to learn details of Access Points, for example their location and number of connected users.** |
| [/queries/zones/{zoneId}<br> /accessPoints/{accessPointId}](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/operations/location/apByIdGET) | accessPoint data for a single PoA | |
## MEC 013 v2.1.1 - (published, not available on forge)
| [/subscriptions/zonalTraffic](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/zonalTrafficSubGET) | Subscription related to changes for a zone: users (devices) entering zone, exiting zone, transition across access points within a zone. <br><br> Input = <ul><li> zoneId </li><li> interestRealm </li><li> userEventCriteria </li><li> duration of reporting </li></ul> | Notification == Zonal Presence Notification <br><br> As a MEC Sandbox User or MEC App, I use this notification to monitor changes in a zone. |
| [/subscriptions/userTracking](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/userTrackingSubGET) | Subscription related to changes of a specific user: zone enter, zone exit, transition across points of access. <br><br> Input = <ul><li> address (device id, user id), </li><li> userEventCriteria </li></ul> | Notification == Zonal Presence Notification <br><br> As a MEC Sandbox User or MEC App, I use this notification to track location changes for a specific user (or device). |
| [/subscriptions/zonalStatus](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/zoneStatusSubGET) | Subscription related to changes in zone status: # of users in a zone, # of users per AP in a zone, etc. <br><br> Input = <ul><li> zoneId </li><li> numberOfUsersZoneThreshold </li><li> numberOfUsersAPThreshold </li></ul> | Notification == Zonal Status Notification <br><br> As a MEC Sandbox User or MEC App, I use this notification to monitor changes in a zone. |
| [/subscriptions/area/circle](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/areaCircleSubGET)<br><br>*New STF599* | Subscription to monitor the location of a specific user (device) or list of users in relation to a circle area, geo-located circle (defined by coordinates and a radius). <br><br> Subscription input: <ul><li> UE address(s) </li><li> Circle info: latitude, longitude, radius </li><li> accuracy </li><li> criteria: entering, leaving </li><li> check immediately on subscription </li><li> max frequency of reporting </li><li> duration of reporting </li><li> max count (total number of notifications) </li></ul> | Notification (Subscription Notification) – issued on criteria: <ul><li> UE address </li><li> Current UE Location </li></ul><br><br> As a MEC Sandbox User or MEC App, I use this notification to monitor a specific location area of my choosing (circle area) in relation to a device or set of devices, also of my choosing. |
| [/subscriptions/distance](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/distanceSubGET)<br><br>*New STF599* | Subscription to monitor the distance of a specific set of user devices (UE), towards another set of user devices. <br><br> Subscription input: <ul><li> reference address(s) </li><li> monitored address(s) </li><li> distance </li><li> accuracy </li><li> criteria: all within, any within, all beyond, all beyond </li><li> check immediately on subscription </li><li> max frequency of reporting </li><li> duration of reporting </li><li> max count (total number of notifications) </li></ul> | Notification (Subscription Notification) – issued on criteria: <ul><li> address and current location for all UEs (reference and monitored) </li><li> notification criteria: all within, any within, all beyond, all beyond </li></ul><br><br> As a MEC Sandbox User or MEC App, I use this notification to monitor the distance status between two user devices (UEs or terminals) or two sets if user devices. |
| [/subscriptions/periodic](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/rep/mec/gs013-location-api/raw/v2.1.1/LocationAPI.yaml#/location/periodicSubGET)<br><br>*New STF599* | Subscription to monitor the location of a specific set of user devices (UE). <br><br>Subscription input: <ul><li> UE address(s) </li><li> max frequency of reporting </li><li> duration or reporting </li><li> max count (total number of notifications) </li></ul> | Notification (Subscription Notification) issued on criteria: period (frequency), duration, total # of notifications. <br><br> As a MEC Sandbox User or MEC App, I use this notification to periodicaly monitor the geo-location of a specific device or set of devices. |
| Timestamp == string (date and time) | Timestamp == <br>- Uint32 seconds in Unix-time since Jan 1 1970 <br>- Uint32 nanoseconds in Unix-time | Modified - change in format |
| Location Info == | - latitude <br>- longitude <br>- altitude <br>- accuracy | Modified - much more complex type. See Section 6.5.3. Includes v.1.1.1 parameters, plus: shape information, velocity, etc. |
| /users/{userId} <br><br> UE Location Look-up of a single UE | /v2/users <br><br> UE Location Lookup for a specific UE **or a group of UEs** | Modified <br><br> Query input: <br>- zoneId(s) <br>- accessPointId(s)<br>- UE address(s) |
|- | /v2/queries/distance | Addition – user can query the distance between a terminal an either a geo-location or another terminal (need to know addresses for both terminals) <br><br> Query input: <br>-Parameter 1 == UE address <br>-Parameter 2 == geo-location (distance between UE and this point), <br>or UE address (distance between two UEs <br><br>*STF587 Milestone D consideration, depending on remaining time and effort* |
|- | /v2/subscriptions/periodic | Addition - user can subscribe notifications to periodic location notifications <br><br> Subscription input: <br>- address of terminal to report <br>- accuracy <br>- frequency of reporting (period) <br>- duration <br><br> Notification (Subscription Notification) – issued periodically: <br>- UE address <br>- Current UE location: accuracy, altitude, latitude, longitude, time-stamp <br><br>*STF587 Milestone D consideration, depending on remaining time and effort* |
|- | /v2/subscriptions/distance | Addition - user can subscribe to changes in distance between a UE (or set of UEs) and a reference UE (or set) <br><br> Subscription input: <br>- reference address(s) <br>- monitored address(s) <br>- distance <br>- accuracy <br>- criteria: all within, any within, all beyond, all beyond<br>- check immediately on subscription <br>- max frequency of reporting <br>- duration <br>- max count - number of notifications <br><br>Notification (Subscription Notification) – issued on criteria: <br>- address and current Location for all UEs: reference and monitored <br><br>*STF587 Milestone D consideration, depending on remaining time and effort* |
|- | /v2/subscriptions/area/circle | Addition - user can subscribe to user(s) location in relation to a geo-located circle (defined by coordinates and a radius) <br><br> Subscription input: <br>- UE address(s) <br>- Circle info: latitude, longitude, radius <br>- accuracy <br>- criteria: entering, leaving <br>- check immediately on subscription <br>- max frequency of reporting <br>- duration <br>- max count - number of notifications <br><br>Notification (Subscription Notification) – – issued on criteria: <br>- UE address <br>- Current UE Location <br><br>*STF587 Milestone D consideration, depending on remaining time and effort* |
