We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Location Server Open RESTful API Specification - FIWARE Forge Wiki

Location Server Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Dedicated API Introduction

Please check the following FI-WARE Open Specification Legal Notice (essential patents license) [1] to understand the rights to use these specifications.

Introduction to the Restful Network API for Terminal Location

Network API for Terminal Location

The Network API for Terminal Location is a RESTful, resource-oriented API accessed via HTTP that uses XML-based representations for information interchange.
In the scope of FIWARE, a subset of the normalized OMA-TS-REST_NetAPI_TerminalLocation REST_NetAPI_TerminalLocation specification is applied. Exact implemented subset is described in following chapters (please refer to below figure).
To summarize, the following operations are supported :
  • Obtain the current terminal location
  • Manage client-specific subscriptions to periodic notifications
  • Manage client-specific subscriptions to area (circle) notifications

Intended Audience

This specification is intended for both software developers and Cloud Providers. For the former, this document provides a full specification of how to interoperate with Location GE platform that implements Terminal Location API. For the latter, this specification indicates the interface to be provided in order to clients to interoperate with Location GE to provide the described functionalities. To use this information, the reader should firstly have a general understanding of the Location Generic Enabler and be familiar with :

  • ReSTful web services
  • HTTP/1.1
  • JSON and/or XML data serialization formats."

API Change History

This version of the Network API for Terminal Location Guide replaces and obsoletes all previous versions.

The following APIs defines the baseline reference API :

[REST_NetAPI_Common] Common definitions for RESTful Network APIs, Open Mobile Alliance™, OMA-TSREST_NetAPI_Common-V1_0, URL: REST_NetAPI_Common

[REST_NetAPI_TerminalLocation] RESTful Network API for Terminal Location, Open Mobile Alliance™, OMA-TSREST_NetAPI_TerminalLocation-V1_0, URL: REST_NetAPI_TerminalLocation

History of specific changes that overrides this baseline is described in the following table.

Date Comment
Apr 18, 2012
  • Initial Version
Sept 26, 2012
  • Complete Support for url-form-encoded and json API format
  • Add Periodic Subscription service API
Jan 30, 2014
  • Complete support for optional API extension for NGSI Pub/Sub integration

How to Read This Document

In the whole document it is taken the assumption that reader is familiarized with REST architecture style. Along the document, some special notations are applied to differentiate some special words or concepts. The following list summarizes these special notations.
  • A bold, mono-spaced font is used to represent code or logical entities, e.g., HTTP method (GET, PUT, POST, DELETE).
  • An italic font is used to represent document titles or some other kind of special text, e.g., URI.
  • The variables are represented between brackets, e.g. {id} and in italic font. When the reader find it, can change it by any value.

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at the Summary of FI-WARE Open Specifications. For more details about the Location GE that this API is based upon, please refer to "Architecture Description of Location GE". Related documents, including an Architectural Description, are available at the same site."

General Location Server REST API Information

The specification provides resource definitions, the HTTP verbs applicable for each of these resources, and the element data structures, as well as support material including flow diagrams and examples using the various supported message body formats (i.e. XML).

Resources Summary

The {apiVersion} URL variable SHALL have the value “v1” to indicate that the API corresponds to the “v1” OMA version of the associated specification. See REST_NetAPI_Common which specifies the semantics of this variable.

serverRoot = server base url (hostname+port)

Authentication

No specific authentication scheme is put in place at HTTP level (no SSL over HTTP). Applicative authentication is performed thanks to request parameters.

Representation Format

Important notice :

The request support different data serialization format :

  • XML : the request format specified in the Content-Type header is supposed to be application/xml MIME type.
  • form-urlencoded : the request format specified in the Content-Type header is supposed to be application/x-www-form-urlencoded MIME type.
  • JSON : the request format specified in the Content-Type header is supposed to be application/json MIME type.

Note: only the request body is encoded as application/x-www-form-urlencoded, the response is still encoded as XML or JSON depending on the preference of the client and the capabilities of the server. Names and values MUST follow the application/x-www-form-urlencoded character escaping rules from W3C_URLENC .

Different format examples are provided for each kind of services, when applicable.

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Resource Identification

The resource identification used by the API in order to identify unambiguously the resource will be provided over time. For HTTP transport, this is made using the mechanisms described by HTTP protocol specification as defined by IETF RFC-2616.

Links and References

None

Limits

A maximum of 15 location query requests per second is allowed.

Versions

Querying the version is NOT supported (already included in the resources tree).

Faults

Please find below a list of possible fault elements and error codes

Associated Error CodesDescriptionExpected in All Requests?
400 (“Bad Request”)The document in the entity-body, if any, contains an error message. Hopefully the client can understand the error message and use it to fix the problem. [YES]
404 (“Not Found”)The requested URI doesn’t map to any resource. The server has no clue what the client is asking for. [YES]
500 (“Internal Server Error”)There’s a problem on the server side. The document in the entity-body, if any, is an error message. The error message probably won’t do much good, since the client can’t fix the server problem.[YES]

Data Types

XML NameSpaces

The XML namespace for the Terminal Location data types is:

      urn:oma:xml:rest:netapi:terminallocation:1 

The 'common' namespace prefix is used in the present document refers to the XML namespace of the data types defined in REST_NetAPI_Common  :

      urn:oma:xml:rest:netapi:common:1

Requester

This section details the requester string format accepted by the API.

The format has the following string pattern : <service> : <password>.

To be authorized, the following condition shall be met :

  • Service <service> must exists in the LOCS database
  • Service must be associated to a ServiceProvider with access password equal to <password>

Structures

This subsection describes the XML structure used in the Terminal Location API.

Type:CallbackReference

There is no constraints on content format of call back data , except if LOCS services are used with Context Broker. In that case, NGSI Integration is achieved by defining specific content for the following properties :

  • notifyURL : Context Broker URL where location updates are notified.
  • callbackData : NGSI entity id reference/location attribute to update. By default, ngsi:<entity id>/position is equivalent to ngsi:<entity id> only using default location attribute name.

Nota : locevent attribute name on entity is mandatory.

Type:TerminalLocation

A type containing device address, retrieval status and location information. As this can be related to a query of a group of terminal devices, the locationRetrievalStatus element is used to indicate whether the information for the device was retrieved or not, or if an error occurred.

Element Type Optional Description
address xsd:anyURI No Address of the terminal to which the location information (tel URI)
locationRetrievalStatus common:RetrievalStatus No Status of retrieval for this terminal address
currentLocation LocationInfo Yes Location of terminal. It is only provided if location Retrieval Status = Retrieved.
errorInformation common:ServiceError Yes Must be included when location Retrieval Status = Error. This is the reason for the error.

Type:TerminalLocationList

A type containing a list of terminal locations.

Element Type Optional Description
terminalLocation TerminalLocation[1..unbounded] No Collection of the terminal locations.

Type:LocationInfo

A type containing location information with latitude, longitude and altitude, in addition the accuracy and a timestamp of the information are provided.

Element Type Optional Description
latitude xsd:float No Location latitude.
longitude xsd:float No Location longitude.
altitude xsd:float Yes Location altitude.
accuracy xsd:int No Accuracy of location provided in meters.
timestamp xsd:datetime No Date and time that location was collected.

Type:PeriodicNotificationSubscription

A type containing data for periodic notification.

Element Type Optional Description
clientCorrelator xsd:string Yes A correlator that the client MAY use to tag this particular resource representation during a request to create a resource on the server. In case the element is present, the server SHALL not alter its value, and SHALL provide it as part of the representation of this resource. In case the element is not present, the server SHALL NOT generate it.
resourceURL xsd:anyURI Yes Self referring URL. The resourceURL SHALL NOT be included in POST requests by the client, but MUST be included in POST requests representing notifications by the server to the client, when a complete representation of the resource is embedded in the notification. The resourceURL MUST also be included in responses to any HTTP method that returns an entity body, and in PUT requests.
link common:Link[0..unbounded] Yes Link to other resources that are in relationship with the resource.
callbackReference common:CallbackReference No Notification callback definition. See REST_NetAPI_Common for details. In case of NGSI integration with Pub/Sub broker see Nota above.
requester xsd:datetime Yes Mandatory for POST request for subscription creation. It identifies the entity that is requesting the Information. See Requester detailed format
address xsd:anyURI No Addresses of terminal to monitor (e.g tel URI).
requestedAccuracy xsd:float No Accuracy of the provided location in meters.
frequency xsd:int No Maximum frequency (in seconds) of notifications per subscription (can also be considered minimum time between notifications).
duration xsd:int No Period of time (in seconds) notifications are provided for.

Type:CircleNotificationSubscription

A type containing data for notification, when the area is defined as a circle.

Element Type Optional Description
clientCorrelator xsd:string Yes A correlator that the client MAY use to tag this particular resource representation during a request to create a resource on the server. In case the element is present, the server SHALL not alter its value, and SHALL provide it as part of the representation of this resource. In case the element is not present, the server SHALL NOT generate it.
resourceURL xsd:anyURI Yes Self referring URL. The resourceURL SHALL NOT be included in POST requests by the client, but MUST be included in POST requests representing notifications by the server to the client, when a complete representation of the resource is embedded in the notification. The resourceURL MUST also be included in responses to any HTTP method that returns an entity body, and in PUT requests.
link common:Link[0..unbounded] Yes Link to other resources that are in relationship with the resource.
callbackReference common:CallbackReference No Notification callback definition.See REST_NetAPI_Common for details. In case of NGSI integration with Pub/Sub broker see Nota above.
requester xsd:datetime Yes Mandatory for POST request for subscription creation. It identifies the entity that is requesting the Information.See Requester detailed format
address xsd:anyURI No Addresses of terminal to monitor (e.g tel URI).
latitude xsd:float No Latitude of center point.
longitude xsd:float No Lontitude of center point.
radius xsd:int No Radius of circle around center point in meters.
trackingAccuracy xsd:float No Number of meters of acceptable error in tracking location.
enteringLeavingCriteria EnteringLeavingCriteria No Indicates whether the notification should occur when the terminal enters or leaves the target area.
frequency xsd:int No Maximum frequency (in seconds) of notifications per subscription (can also be considered minimum time between notifications).
duration xsd:int No Period of time (in seconds) notifications are provided for.
count xsd:int No Maximum number of notifications.

Type:SubscriptionNotification

A type containing the notification subscription.

Element Type Optional Description
callbackData xsd:string Yes CallbackData if passed by the application in the receipt Request element during the associated subscription operation.See REST_NetAPI_Common for details
terminalLocation TerminalLocation[1..unbounded] No Collection of the terminal locations.
enteringLeavingCriteria EnteringLeavingCriteria Yes Indicates whether the notification was caused by the terminal entering or leaving the target area.
link common:Link[0..unbounded] Yes Link to other resources that are in relationship with the resource.

Type:SubscriptionCancellationNotification

A type containing the subscription cancellation notification.

Element Type Optional Description
callbackData xsd:string Yes CallbackData if passed by the application in the receipt Request element during the associated subscription operation.See REST_NetAPI_Common for details
address xsd:anyURI Yes Address of terminal if the error applies to.
reason common:ServiceError No Reason notification is being discontinued.
link common:Link[0..unbounded] Yes Link to other resources that are in relationship with the resource.

Type:RequestError

A type containing request error response description.

Element Type Optional Description
serviceException common:serviceException Yes Used when request execution fails (format error, position method failure, etc..)
policyException common:policyException Yes Used when request execution is not authorized.

API Operations

The following chapter gives a detailed overview of the resources defined in this specification, the data type of their representation, the allowed HTTP methods, and some examples.

Location Query

Purpose: poll terminal location

Resource HTTP Verb Base URI Data Structures Description
Terminal location GET "http://{serverRoot}/location/{apiVersion}/queries/location" TerminalLocationList return current location of the terminal or multiple terminals

This figure below shows a scenario to return location for a single terminal or a group of terminals.

The resource:

  • To get the location information for a single terminal or a group of terminals, read the resource below with the URL parameters containing terminal address or addresses
    http://{serverRoot}/location/{apiVersion}/queries/location

File:LocationQuery.png

Outline of flow:

1. An application requests the distance between two terminals by using GET with the resource URL and providing two different terminal addresses as Request URL parameters. 2. It receives the terminal distance information.

Detailed resources description

GET Request :

If the format of the request is not correct, a ServiceException will be returned If the requester parameter is present and the requester is not authorized, a PolicyException will be returned.

Name Type Optional Description
requester xsd:anyURI No It identifies the entity that is requesting the information (See Requester specific format). If the requester is not authorized to retrieve location info, a policy exception will be returned.
address xsd:anyURI[1..unbounded] No Address(es) of the terminal device(s) for which the location information is requested. Examples: (e.g tel URI tel:+19585550100,..)
requestedAccuracy xsd:int No Accuracy of location information requested.
acceptableAccuracy xsd:int No Accuracy that is acceptable for a response.
maximumAge xsd:int Yes Maximum acceptable age (in seconds) of the location information that is returned.
responseTime xsd:int Yes Indicates the maximum time (in seconds) that the application can accept to wait for a response.
tolerance DelayTolerance No Indicates the priority of response time versus accuracy.
ngsiUpdateURL xsd:string Yes URL of Context Broker Server. Only in cased of LOCS NGSI integration to Context Broker.
ngsiEntity xsd:string Yes description of NGSI registered entity position attribute to update.

Response codes

Code Description
200 Request is OK
400 Request is KO

Examples

Application/xml format

Example 1: (one terminal address, qop (quality of positioning accuracy) acceptable but does not match requested one)

Request :

GET /location/v1/queries/location?requester=test:test&address=33611223344&requestedAccuracy=50&acceptableAccuracy=60
 &maximumAge=100&tolerance=DelayTolerant HTTP/1.1
 Accept: application/xml
 Host: example.com

Response :

 HTTP/1.1 200 OK
 Content-Type: application/xml
 Content-Length: nnnn
 Date: Thu, 02 Jun 2011 02:51:59 GMT

 <?xml version="1.0" encoding="UTF-8"?>
 <tl:terminalLocationList xmlns:common="urn:oma:xml:rest:netapi:common:1"  xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
  <tl:terminalLocation>
   <tl:address>33611223344</tl:address>
   <tl:locationRetrievalStatus>Retrieved
   </tl:locationRetrievalStatus>
   <tl:currentLocation>
    <tl:latitude>49.999737</tl:latitude>
    <tl:longitude>-60.00014</tl:longitude>
    <tl:altitude>30.0</tl:altitude>
    <tl:accuracy>55</tl:accuracy>
    <tl:timestamp>2012-04-17T09:21:32.893+02:00</tl:timestamp>
   </tl:currentLocation>
   <tl:errorInformation>
    <common:messageId>QOP_NOT_ATTAINABLE</common:messageId>
    <common:text>The requested QoP cannot be provided.</common:text>
   </tl:errorInformation>
  </tl:terminalLocation>
 </tl:terminalLocationList>

Example 2: (format error, missing address)

Request :

GET /location/v1/queries/location?requester=test:test&requestedAccuracy=50&acceptableAccuracy=60
 &maximumAge=100&tolerance=DelayTolerant HTTP/1.1
 Accept: application/xml
 Host: example.com

Response :

 HTTP/1.1 400 BadRequest
 Content-Type: application/xml
 Content-Length: nnnn
 Date: Thu, 02 Jun 2011 02:51:59 GMT

 <?xml version="1.0" encoding="UTF-8"?>
 <common:RequestError xmlns:common="urn:oma:xml:rest:netapi:common:1" xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
  <common:serviceException>
   <common:messageId>FORMAT_ERROR</common:messageId>
   <common:text> A protocol element in the request has invalid format.</common:text>
  </common:serviceException>
 </common:RequestError>

Example 3: (unauthorized requester, bad password)

Request :

GET /location/v1/queries/location?requester=test:badpassword&address=33611223344&requestedAccuracy=50&acceptableAccuracy=60
 &maximumAge=100&tolerance=DelayTolerant HTTP/1.1
 Accept: application/xml
 Host: example.com

Response :

 HTTP/1.1 400 BadRequest
 Content-Type: application/xml
 Content-Length: nnnn
 Date: Thu, 02 Jun 2011 02:51:59 GMT

 <?xml version="1.0" encoding="UTF-8"?>
 <common:RequestError xmlns:common="urn:oma:xml:rest:netapi:common:1" xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
  <common:policyException>
   <common:messageId>UNAUTHORIZED_APPLICATION</common:messageId>
   <common:text>The requested location-based application is not allowed to access the location server or a wrong password has been supplied.</common:text>
  </common:policyException>
 </common:RequestError>

Example 4 : Using NGSI integration

Request :

 GET   /location/v1/queries/location?requester=test:test&address=33611223344&requestedAccuracy=40&acceptableAccuracy=60
 &maximumAge=1000&tolerance=DelayTolerant&ngsiUpdateURL=http://orion-psb.testbed.fi-ware.eu:1026&ngsiEntity=33611223344 HTTP/1.1
 Accept: application/xml
 Host: example.com

Response :

HTTP/1.1 200 No Content

When the location session is complete, the following attribute position update notification is sent Context Broker end-point URL.

Application/json format

Request :

 GET location/v1/queries/location?requester=test:test&address=33611223344&tolerance=LowDelay&requestedAccuracy=1000
&acceptableAccuracy=1000 HTTP/1.1
 Content-Type: application/json
 Accept: application/json
 Host: example.com
 

Response :

 HTTP/1.1 200 OK
 Content-Type: application/json
 Content-Length: nnnn

 {"terminalLocationList": {"terminalLocation": {
 "address": "tel:+19585550100",
 "currentLocation": {
 "accuracy": "100",
 "altitude": "1001.0",
 "latitude": "-80.86302",
 "longitude": "41.277306",
 "timestamp": "2011-06-04T00:27:23.000Z"
 },
 "locationRetrievalStatus": "Retrieved"
 }}}
 

Periodic Notification Subscription

Purpose: Periodic location subscription

This resource is used to control subscriptions for periodic location notification for a particular client.

Resource HTTP Verb Base URI Data Structures Description
Periodic notification subscriptions POST "http://{serverRoot}/location/{apiVersion}/subscriptions/periodic" PeriodicNotificationSubscription create new subscription.
Periodic individual notification subscription DELETE "http://{serverRoot}/location/{apiVersion}/subscriptions/periodic/{subscriptionid}" None delete one subscription.
Client notifications on periodic terminal location retrieved POST Notification URL provided by client in notification subscription SubscriptionNotification or SubscriptionCancellationNotification signal notification

This figure below shows a scenario to control subscriptions for periodic notifications about terminal location for a particular client.

The resource:

  • To start subscription to periodic notifications about terminal location for a particular client, create new resource under
      http://{serverRoot}/location/{apiVersion}/subscriptions/periodic
  • To delete an individual subscription for an individual subscription for periodic notifications about terminal location for a particular client, use the resource
      http://{serverRoot}/location/{apiVersion}/subscriptions/periodic/{subscriptionId}

File:PeriodicSubscription.png

Outline of flow:

1. An application creates a new periodic notification subscription for the requesting client by using POST and receives the resulting resource URL containing subscriptionId.

2. At set-up frequency, The REST service on the server notifies the application of current location information using POST to the application supplied notifyURL.

3. An application deletes a subscription for periodic location notification and stops notifications for a particular client by using DELETE to resource URL containing subscriptionId.

Detailed resources description

POST Request :

This operation is used to create new periodic notification subscription for the requesting client. If correlator parameter is set, this value is used to build a predictable subscription URL with the a variable end string part of ‘sub<correlator string>’

If the format of the request is not correct, a ServiceException will be returned If the requester parameter is present and the requester is not authorized, a PolicyException will be returned.

DELETE Request :

This operation is used to delete a subscription for periodic location notifications and stop notifications for a particular client. No URL parameters.

Response Codes

Code Description
201 Subscription request created
204 No content
400 Request is KO

Examples

Application/xml format

Example 1: Add new subscription

Request :

 POST /location/v1/subscriptions/periodic HTTP/1.1
 Accept: application/xml
 Host: example.com
 Content-Length: nnnn

 <?xml version="1.0" encoding="UTF-8"?>
 <tl:periodicNotificationSubscription xmlns:common="urn:oma:xml:rest:netapi:common:1"
xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
 <tl:clientCorrelator>0003</tl:clientCorrelator>
 <tl:callbackReference>
   <common:notifyURL>http://application.example.com/notifications/LocationNotification</common:notifyURL>
   <common:callbackData>4444</common:callbackData>
 </tl:callbackReference>
 <tl:requester>test:test</tl:requester>
 <tl:address>tel:+19585550100</tl:address>
 <tl:requestedAccuracy>10</tl:requestedAccuracy>
 <tl:frequency>10</tl:frequency>
 <tl:duration>100</tl:duration>
 </tl:periodicNotificationSubscription>
 

Response :

 HTTP/1.1 201 Created
 Content-Type: application/xml
 Location: http://example.com/location/v1/subscriptions/periodic/sub003
 Content-Length: nnnn
 Date: Thu, 02 Jun 2011 02:51:59 GMT

 <?xml version="1.0" encoding="UTF-8"?>
 <tl:periodicNotificationSubscription xmlns:common="urn:oma:xml:rest:netapi:common:1"  xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
 <tl:clientCorrelator>0003</tl:clientCorrelator>
 <tl:resourceURL>http://example.com/location/v1/subscriptions/periodic/sub0003</tl:resourceURL>
 <tl:callbackReference>
 <common:notifyURL>http://application.example.com/notifications/LocationNotification</common:notifyURL>
 <common:callbackData>4444</common:callbackData>
 </tl:callbackReference>
 <tl:requester>test:test</tl:requester>
 <tl:address>tel:+19585550100</tl:address>
 <tl:requestedAccuracy>10</tl:requestedAccuracy>
 <tl:frequency>10</tl:frequency>
 <tl:duration>100</tl:duration>
 </tl:periodicNotificationSubscription>
 

Subscription notification :

 POST /notifications/LocationNotification HTTP/1.1
 Content-Type: application/xml
 Accept: application/xml
 Host: application.example.com
 Content-Length: nnnn

 <?xml version="1.0" encoding="UTF-8"?>
 <tl:subscriptionNotification xmlns:common="urn:oma:xml:rest:netapi:common:1" xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
 <common:callbackData>4444</common:callbackData>
 <tl:terminalLocation>
 <tl:address>tel:+19585550100</tl:address>
 <tl:locationRetrievalStatus>Retrieved</tl:locationRetrievalStatus>
 <tl:currentLocation>
 <tl:latitude>-80.86302</tl:latitude>
 <tl:longitude>41.277306</tl:longitude>
 <tl:altitude>1001.0</tl:altitude>
 <tl:accuracy>100</tl:accuracy>
 <tl:timestamp>2011-06-02T00:27:23.000Z</tl:timestamp>
 </tl:currentLocation>
 </tl:terminalLocation>
 <tl:link rel="PeriodicNotificationSubscription"
href="http:/location/v1/subscriptions/periodic/sub0003"/>
 </tl:subscriptionNotification>
 

Example 2: Delete subscription

Request :

 DELETE /location/v1/subscriptions/periodic/sub0003 HTTP/1.1
 Accept: application/xml
 Host: example.com
 

Response :

 HTTP/1.1 204 No Content
 Date: Thu, 02 Jun 2011 02:51:59 GMT
 

Application/x-www-form-urlencoded format

Example 1: Add new subscription

Request :

 POST /location/v1/subscriptions/periodic HTTP/1.1
 Accept: application/xml
 Host: example.com
 Content-Type: application/x-www-form-urlencoded
 Content-Length: nnnn

 clientCorrelator=0003&
 notifyURL=http%3A%2F%2Fapplication.example.com%2Fnotifications%2FLocationNotification&
 callbackData=4444&
 requester=test%3Atest&
 address=tel%3A%2B19585550100&
 requestedAccuracy=10&
 frequency=10&
 duration=100
 

Response :

 HTTP/1.1 201 Created
 Content-Type: application/xml
 Location: http://example.com/location/v1/subscriptions/periodic/sub003
 Content-Length: nnnn
 Date: Thu, 02 Jun 2011 02:51:59 GMT

 <?xml version="1.0" encoding="UTF-8"?>
 <tl:periodicNotificationSubscription xmlns:common="urn:oma:xml:rest:netapi:common:1"  xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
 <tl:clientCorrelator>0003</tl:clientCorrelator>
 <tl:resourceURL>http://example.com/location/v1/subscriptions/periodic/sub0003</tl:resourceURL>
 <tl:callbackReference>
 <common:notifyURL>http://application.example.com/notifications/LocationNotification</common:notifyURL>
 <common:callbackData>4444</common:callbackData>
 </tl:callbackReference>
 <tl:requester>test:test</tl:requester>
 <tl:address>tel:+19585550100</tl:address>
 <tl:requestedAccuracy>10</tl:requestedAccuracy>
 <tl:frequency>10</tl:frequency>
 <tl:duration>100</tl:duration>
 </tl:periodicNotificationSubscription>
 

Application/json format

Example 1: Add new subscription

Request :

 POST /location/v1/subscriptions/periodic HTTP/1.1
 Content-Type: application/json
 Accept: application/json
 Host: example.com
 Content-Length: nnnn

 {"periodicNotificationSubscription": {
 "address": "tel:+19585550100",
 "callbackReference": {
 "callbackData": "4444",
 "notifyURL": "http://application.example.com/notifications/LocationNotification"
 },
 "checkImmediate": "true",
 "clientCorrelator": "0003",
 "frequency": "10",
 "duration": "100",
 "requestedAccuracy": "10"
 }}
 

Response :

 HTTP/1.1 201 Created
 Content-Type: application/json
 Location: http://example.com/location/v1/subscriptions/periodic/sub0003
 Content-Length: nnnn

 {"periodicNotificationSubscription": {
 "address": "tel:+19585550100",
 "callbackReference": {
 "callbackData": "4444",
 "notifyURL": "http://application.example.com/notifications/LocationNotification"
 },
 "checkImmediate": "true",
 "clientCorrelator": "0003",
 "frequency": "10",
 "duration": "100",
 "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/periodic/sub003",
 "requestedAccuracy": "10"
 }}
 

Area (Circle) Notification Subscription

Purpose: Area location subscription

Resource HTTP Verb Base URI Data Structures Description
Area (circle)notification subscriptions POST "http://{serverRoot}/location/{apiVersion}/subscriptions/area/circle" CircleNotificationSubscription create new subscription.
Area (circle)individual notification subscription DELETE "http://{serverRoot}/location/{apiVersion}/subscriptions/area/circle/{subscriptionid}" None delete one subscription.
Client notifications on terminal location changes POST Notification URL provided by client in notification subscription SubscriptionNotification or SubscriptionCancellationNotification signal notification

This figure below shows a scenario to control subscriptions for notification about terminal movement in relation to the geographic area (circle), crossing in and out, for a particular client.

The resource:

  • To start subscription to notifications about terminal movements in relation to the geographic area (circle), crossing in and out, for a particular client, create new resource under
      http://{serverRoot}/location/{apiVersion}/subscriptions/area/circle
  • To delete an individual subscription for notifications about terminal movements in relation to the geographic area (circle), crossing in and out, for a particular client, use the resource
      http://{serverRoot}/location/{apiVersion}/subscriptions/area/circle/{subscriptionId}

File:AreaSubscription.png

Outline of flow:

1. An application creates a new periodic notification subscription for the requesting client by using POST and receives the resulting resource URL containing subscriptionId.

2. When the terminal crosses in or out the specified area (circle), The REST service on the server notifies the application of current location information using POST to the application supplied notifyURL.

3. An application deletes a subscription for periodic location notification and stops notifications for a particular client by using DELETE to resource URL containing subscriptionId.

Detailed resources description

POST Request :

This operation is used to create new movement notification subscription for the requesting client. If correlator parameter is set, this value is used to build a predictable subscription URL with the a variable end string part of ‘sub<correlator string>’

If the format of the request is not correct, a ServiceException will be returned If the requester parameter is present and the requester is not authorized, a PolicyException will be returned.

DELETE Request :

This operation is used to delete a subscription for periodic location notifications and stop notifications for a particular client. No URL parameters.

Response Codes

Code Description
201 Subscription request created
204 No content
400 Request is KO

Examples

Application/xml format

Example 1: Add new subscription

Request :

 POST /location/v1/subscriptions/area/circle HTTP/1.1
 Accept: application/xml
 Host: example.com
 Content-Length: nnnn

 <?xml version="1.0" encoding="UTF-8"?>
 <tl:circleNotificationSubscription xmlns:common="urn:oma:xml:rest:netapi:common:1"
xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
 <tl:clientCorrelator>0003</tl:clientCorrelator>
 <tl:callbackReference>
   <common:notifyURL>http://application.example.com/notifications/LocationNotification</common:notifyURL>
   <common:callbackData>4444</common:callbackData>
 </tl:callbackReference>
 <tl:requester>test:test</tl:requester>
 <tl:address>tel:+19585550100</tl:address>
 <tl:latitude>100.23</latitude>
 <tl:longitude>-200.45</tl :longitude>
 <tl:radius>500</tl :radius>
 <tl:trackingAccuracy>10</tl:trackingAccuracy>
 <tl:enteringLeavingCriteria>Entering</tl:enteringLeavingCriteria>
 <tl:checkImmediate>true</tl:checkImmediate>
 <tl:frequency>10</tl:frequency>
 <tl:duration>100</tl:duration>
 <tl:count>5</tl:count>
 </tl:circleNotificationSubscription>
 

Response :

 HTTP/1.1 201 Created
 Content-Type: application/xml
 Location: http://example.com/location/v1/subscriptions/area/circle/sub003
 Content-Length: nnnn
 Date: Thu, 02 Jun 2011 02:51:59 GMT

 <?xml version="1.0" encoding="UTF-8"?>
 <tl:circleNotificationSubscription xmlns:common="urn:oma:xml:rest:netapi:common:1"  xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
 <tl:clientCorrelator>0003</tl:clientCorrelator>
 <tl:resourceURL>http://example.com/location/v1/subscriptions/area/circle/sub0003</tl:resourceURL>
 <tl:callbackReference>
 <common:notifyURL>http://application.example.com/notifications/LocationNotification</common:notifyURL>
 <common:callbackData>4444</common:callbackData>
 </tl:callbackReference>
 <tl:requester>test:test</tl:requester>
 <tl:address>tel:+19585550100</tl:address>
 <tl:latitude>100.23</tl :latitude>
 <tl:longitude>-200.45</tl :longitude>
 <tl:radius>500</radius>
 <tl:trackingAccuracy>10</tl:trackingAccuracy>
 <tl:enteringLeavingCriteria>Entering</tl:enteringLeavingCriteria>
 <tl:checkImmediate>true</tl:checkImmediate>
 <tl:frequency>10</tl:frequency>
 <tl:duration>100</tl:duration>
 <tl:count>5</tl:count>
 </tl:circleNotificationSubscription>
 

Subscription notification :

 POST /notifications/LocationNotification HTTP/1.1
 Content-Type: application/xml
 Accept: application/xml
 Host: application.example.com
 Content-Length: nnnn

 <?xml version="1.0" encoding="UTF-8"?>
 <tl:subscriptionNotification xmlns:common="urn:oma:xml:rest:netapi:common:1" xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
 <common:callbackData>4444</common:callbackData>
 <tl:terminalLocation>
 <tl:address>tel:+19585550100</tl:address>
 <tl:locationRetrievalStatus>Retrieved</tl:locationRetrievalStatus>
 <tl:currentLocation>
 <tl:latitude>-80.86302</tl:latitude>
 <tl:longitude>41.277306</tl:longitude>
 <tl:altitude>1001.0</tl:altitude>
 <tl:accuracy>100</tl:accuracy>
 <tl:timestamp>2011-06-02T00:27:23.000Z</tl:timestamp>
 </tl:currentLocation>
 </tl:terminalLocation>
 <tl:enteringLeavingCriteria>Entering</tl:enteringLeavingCriteria>
 <tl:link rel="CircleNotificationSubscription"
href="http://example.com/location/v1/subscriptions/area/circle/sub0003"/>
 </tl:subscriptionNotification>
 

Example 2: Delete subscription

Request :

 DELETE /location/v1/subscriptions/area/circle/sub0003 HTTP/1.1
 Accept: application/xml
 Host: example.com
 

Response :

 HTTP/1.1 204 No Content
 Date: Thu, 02 Jun 2011 02:51:59 GMT
 

Example 3: Using NGSI integration with Context Broker

Request :

POST /location/v1/subscriptions/area/circle HTTP/1.1
Accept: application/xml
Host: example.com

 <tl:circleNotificationSubscription xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1" xmlns:common="urn:oma:xml:rest:netapi:common:1">
       <tl:clientCorrelator>0003</tl:clientCorrelator>
       <tl:callbackReference>
         <common:notifyURL>http://orion-psb.testbed.fi-ware.eu:1026</common:notifyURL>
         <common:callbackData>ngsi:33611223344</common:callbackData>
       </tl:callbackReference>
       <tl:requester>test:test</tl:requester>
       <tl:address>tel:+33611223344</tl:address>
       <tl:latitude>43.60091</tl:latitude>
       <tl:longitude>1.44299</tl:longitude>
       <tl:radius>1500</tl:radius>
       <tl:trackingAccuracy>50</tl:trackingAccuracy>
       <tl:enteringLeavingCriteria>Entering</tl:enteringLeavingCriteria>
       <tl:frequency>60</tl:frequency>
       <tl:duration>120</tl:duration>
       <tl:count>2</tl:count>
</tl:circleNotificationSubscription>

Response :

HTTP/1.1 201 Created
Content-Type: application/xml
Location: http://127.0.0.1:10000/location/v1/subscriptions/area/circle/sub003

<tl:circleNotificationSubscription xmlns:common="urn:oma:xml:rest:netapi:common:1" xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
  <tl:clientCorrelator>0003</tl:clientCorrelator>
  <tl:resourceURL>/location/v1/subscriptions/area/circle/sub0003</tl:resourceURL>
  <tl:callbackReference>
    <common:notifyURL>http://orion-psb.testbed.fi-ware.eu:1026</common:notifyURL>
    <common:callbackData>ngsi:33611223344</common:callbackData>
  </tl:callbackReference>
  <tl:requester>test:test
  </tl:requester>
  <tl:address>tel:33611223344</tl:address>
  <tl:latitude>43.60091</tl:latitude>
  <tl:longitude>1.44299</tl:longitude>
  <tl:radius>1500.0</tl:radius>
  <tl:trackingAccuracy>50.0</tl:trackingAccuracy>
  <tl:enteringLeavingCriteria>Entering</tl:enteringLeavingCriteria>
  <tl:checkImmediate>false</tl:checkImmediate>
  <tl:frequency>60</tl:frequency>
  <tl:duration>120</tl:duration>
  <tl:count>2</tl:count>
 </tl:circleNotificationSubscription>

LOCS sends the position/locevent update notification for entering events to Context Broker end-point URL.

Application/x-www-form-urlencoded format

Example 1: Add new subscription

Request :

 POST /location/v1/subscriptions/area/circle HTTP/1.1
 Accept: application/xml
 Host: example.com
 Content-Type: application/x-www-form-urlencoded
 Content-Length: nnnn

 clientCorrelator=0003&
 notifyURL=http%3A%2F%2Fapplication.example.com%2Fnotifications%2FLocationNotification&
 callbackData=4444&
 requester=test%3Atest&
 address=tel%3A%2B19585550100&
 latitude=100.23&
 longitude=-200.45&
 radius=500&
 trackingAccuracy=10&
 enteringLeavingCriteria=Entering&
 checkImmediate=true&
 frequency=10&
 duration=100&
 count=10
 

Response :

 HTTP/1.1 201 Created
 Content-Type: application/xml
 Location: http://example.com/location/v1/subscriptions/area/circle/sub003
 Content-Length: nnnn
 Date: Thu, 02 Jun 2011 02:51:59 GMT

 <?xml version="1.0" encoding="UTF-8"?>
 <tl:circleNotificationSubscription xmlns:common="urn:oma:xml:rest:netapi:common:1"  xmlns:tl="urn:oma:xml:rest:netapi:terminallocation:1">
 <tl:clientCorrelator>0003</tl:clientCorrelator>
 <tl:resourceURL>http://example.com/location/v1/subscriptions/area/circle/sub0003</common:resourceURL>
 <tl:callbackReference>
 <common:notifyURL>http://application.example.com/notifications/LocationNotification</common:notifyURL>
 <common:callbackData>4444</tl:callbackData>
 </tl:callbackReference>
 <tl:requester>test:test</tl:requester>
 <tl:address>tel:+19585550100</tl:address>
 <tl:latitude>100.23</tl :latitude>
 <tl:longitude>-200.45</tl :longitude>
 <tl:radius>500</radius>
 <tl:trackingAccuracy>10</tl:trackingAccuracy>
 <tl:enteringLeavingCriteria>Entering</tl:enteringLeavingCriteria>
 <tl:checkImmediate>true</tl:checkImmediate>
 <tl:frequency>10</tl:frequency>
 <tl:duration>100</tl:duration>
 <tl:count>10</tl:count>
 </tl:circleNotificationSubscription>
 

Application/json format

Example 1: Add new subscription

Request :

 POST /location/v1/subscriptions/area/circle HTTP/1.1
 Content-Type: application/json
 Accept: application/json
 Host: example.com
 Content-Length: nnnn

 {"circleNotificationSubscription": {
 "address": "tel:+19585550100",
 "callbackReference": {
 "callbackData": "4444",
 "notifyURL": "http://application.example.com/notifications/LocationNotification"
 },
 "checkImmediate": "true",
 "clientCorrelator": "0003",
 "enteringLeavingCriteria": "Entering",
 "frequency": "10",
 "duration": "100",
 "count": "10",
 "latitude": "100.23",
 "longitude": "-200.45",
 "radius": "500",
 "trackingAccuracy": "10"
 }}
 

Response :

 HTTP/1.1 201 Created
 Content-Type: application/json
 Location: http://example.com/location/v1/subscriptions/area/circle/sub0003
 Content-Length: nnnn

 {"circleNotificationSubscription": {
 "address": "tel:+19585550100",
 "callbackReference": {
 "callbackData": "4444",
 "notifyURL": "http://application.example.com/notifications/LocationNotification"
 },
 "checkImmediate": "true",
 "clientCorrelator": "0003",
 "enteringLeavingCriteria": "Entering",
 "frequency": "10",
 "duration": "100",
 "count": "10",
 "latitude": "100.23",
 "longitude": "-200.45",
 "radius": "500",
 "resourceURL": "http://example.com/exampleAPI/location/v1/subscriptions/area/circle/sub0003",
 "trackingAccuracy": "10"
 }}
 
Personal tools
Create a book