History

Parlay X API Reference¶

The Parlay X API uses the Simple Object Access Protocol (SOAP) specification for its Web service and relies on an XML schema to access the CLP. This reference describes the Parlay X API functions and its parameters for the input message (request), and gives details of the resulting output message (response).

API Summary¶

The Parlay X API uses the getLocation and getTerminalDistance functions to make and process requests from the CLP.

getLocation

Retrieves the location for a single terminal.

Parameter	Description	Required	Type
requester	Entity that is requesting location information.	Yes	string (xsd:anyURI)
address	Address of the terminal device for which location information is requested.	Yes	ip as int, mac as string (xsd:anyURI)
requestedAccuracy	Desired accuracy for the response (in meters).	Yes	int (xsd:int)
acceptableAccuracy	Limit that is acceptable for the response (in meters).	Yes	int (xsd:int)
maximumAge	Maximum acceptable age of location information that is returned.	No	string (common:TimeMetric)
responseTime	Maximum time that the application can accept to wait for a response.	No	string (common:TimeMetric)
tolerance	Priority of response time.	Yes	string (DelayTolerance)

Example

<xsd:element name="getLocation" type="terminal_location_local_xsd:getLocation"/>
<xsd:complexType name="getLocation">
    <xsd:sequence>
        <xsd:element name="requester" type="xsd:anyURI" minOccurs="0" maxOccurs="1"/>
        <xsd:element name="address" type="xsd:anyURI"/>
        <xsd:element name="requestedAccuracy" type="xsd:int"/>
        <xsd:element name="acceptableAccuracy" type="xsd:int"/>
        <xsd:element name="maximumAge" type="parlayx_common_xsd:TimeMetric" 
                     minOccurs="0" maxOccurs="1"/>
        <xsd:element name="responseTime" type="parlayx_common_xsd:TimeMetric" 
                     minOccurs="0" maxOccurs="1"/>
        <xsd:element name="tolerance" type="terminal_location_xsd:DelayTolerance"/>
    </xsd:sequence>
</xsd:complexType>

requester
Identifies the entity that is requesting the information from the CLP.
The application invokes the request operation on behalf of this entity. The request operation can be invoked without the application authenticating the requester, in which case, the requesting entity is the application itself. The CLP uses a client ID, similar to a Google developer key, to identify a requesting application. The Client ID is a UUID issued by Clearwire to authorized users, and is used to establish the quality of service available to the requesting application.
Required	Yes
Type	string (xsd:anyURI)
Input Value	Client ID issued by Clearwire. See the Parlay X Resources and Tools page.
Return Value	None. If the requester is not authorized to retrieve location information, a fault (POL0002) is returned to the application.

address
Address of the terminal device for which the location information is requested.
The CLP uses the SIP URI scheme defined in the RFC 3261 Memo as a means to specify terminal addresses. A SIP URI takes the form: `sip:user:password@host:port;uri-parameters?headers`
RFC 3261 defines a user header that indicates what type of data is contained in the user part of the SIP URI. Acceptable values for the user URI parameters are: IP v4 address (ip) and WiMAX MAC address (mac)
The CLP does not require a password component, and all requests are made to the domain clearwire-wmx.net. Typical requests use the IP address type of query.
Example SIP URIs:
`sip:192.168.0.1@clearwire-wmx.net;user=ip`
`sip:aabbccddeeff@clearwire-wmx.net;user=mac`
`sip:3105551212@clearwire-wmx.net;user=tn`
`sip:charles@clearwire-wmx.net`
Required	Yes
Type	string (xsd:anyURI)
Input Value	URI for a single terminal: ip as integer, mac as alphanumeric
Return Value	None. If a group URI is specified, a fault is returned to the application.

requestedAccuracy
Accuracy of requested location information.
The accuracy requested is the desired accuracy for the response. The `requestedAccuracy` expresses the range (in meters) in which the application wishes to receive location information. This can influence the choice of location technology to use. For example, cell sector location could be suitable for requests specifying 1000 meters, but GPS technology is required for requests below 100 meters. Currently, the CLP only supports cell sector resolution, and no policies are applied to the `requestedAccuracy` parameter; thus, this element has no effect.
Required	Yes
Type	int (xsd:int)
Input Value	Recommended value is `800`.
Return Value	If an accuracy request is supported, the return value is the range of accuracy for the response, in meters. For example, 804. If the accuracy requested cannot be supported, a fault (POL0230) is returned to the application.

acceptableAccuracy
Accuracy that is acceptable for a response.
The acceptable accuracy is the limit acceptable to the requester. The `acceptableAccuracy` expresses the range (in meters) that the application considers useful. If the location cannot be determined within this range, then the application would prefer not to receive the information. For instance, a taxi tracking service to determine the closest taxi to a person for promptness would not be useful if the accuracy cannot be provided within 1000 meters.
Required	Yes
Type	int (xsd:int)
Input Value	Recommended value is `5000`.
Return Value	If the accuracy of the location is within the acceptable accuracy limit, the actual location is returned. If the accuracy of the location is not within the acceptable accuracy limit, the location is not returned; instead a ServiceException fault (SVC0200) is returned to the application.

maximumAge
Maximum acceptable age of the location information that is returned.
The `maximumAge` expresses the maximum age of location information that the application considers useful. Currently, this parameter has no effect.
Required	No
Type	string (common:TimeMetric)
Input Value
Return Value	None.

responseTime
Indicates the maximum time that the application can accept to wait for a response. Currently, the CLP provides immediate responses; thus, this parameter has no effect.
Required	No
Type	string (common:TimeMetric)
Input Value
Return Value	None

tolerance
Indicates the priority of response time. Since the CLP only supports cell sector resolution positioning, this parameter has no effect.
Required	Yes
Type	string (DelayTolerance)
Input Value	NoDelay, LowDelay, or DelayTolerant. Recommended value is `NoDelay`.
Return Value	None. If tolerance is indicated, the priority of accuracy, response time, and maximum acceptable age are affected. If tolerance is not indicated, a fault (SVC002—invalid input) is returned.

Name	Description	Required	Type
latitude	Location’s horizontal distance, north and south of the equator, in decimal degrees.	Yes	readonly double)
longitude	Location’s angular distance, measured east or west from the prime meridian (Greenwich), in decimal degrees.	Yes	readonly double
altitude	Location’s height (in meters), or `null` if not available.	Yes	readonly double
accuracy	The range (in meters) in which the application receives location information.	Yes	readonly double
timestamp	The timestamp of the time when the result was sent back.	Yes	readonly Date

Service Exception from ES 202 504-1
Error	Description
SVC0001	Service error.
SVC0002	Invalid input value.
SVC0004	No valid address(s) if the requested terminal device address does not exist.
SVC0200	Accuracy out of limit.

Policy Exception from ES 202 504-1
Error	Description
POL0001	Policy error.
POL0002	Privacy error.
POL0006	Groups not allowed.
POL0230	Requested accuracy not supported.

latitude
Latitude of the location.
Latitude represents the location’s horizontal distance, north and south of the equator. Latitude values are expressed as floating point numbers in the range -90.000000 to +90.000000, using decimal degrees (as opposed to minutes and seconds).
Required	Yes
Type	float (xsd:float)
Input Value	-90.000000 to +90.000000
Return Value	Returns the latitude of the location. A positive value indicates a location north of and on the equator. A negative value indicates a location south of the equator.

longitude
Longitude of the location.
Longitude represents the location’s angular distance, measured east or west from the prime meridian (Greenwich). Longitude values are expressed as floating point numbers in the range -180.000000 to +180.000000, using decimal degrees (as opposed to minutes and seconds).
Required	Yes
Type	float (xsd:float)
Input Value	-180.000000 to +180.000000
Return Value	Returns the longitude of the location. A positive value indicates a location east of and on the prime meridian. A negative value indicates a location west of the prime meridian up to the 180th meridian.

Parlay X API Reference¶

API Summary¶

getLocation¶

Request Specification: getLocationRequest¶

Response Specification: getLocationResponse¶

getTerminalDistance¶

Request Specification: getTerminalDistanceRequest¶

Response Specification: getTerminalDistanceResponse¶