Get Position Reference

Last updated
Save as PDF

The getPositionReference() web service is a generic position reference provider. It accepts a lat/lon position and returns the 'best' Position Reference to the specified coordinates. The service obeys the target company's settings related to returning a reference to a nearby landmark. If no reference to a nearby landmark is found, then a reference to the closest city/town is returned.

Using the Division Filter

The service accepts an optional divisionID. If not specified, then the service considers all of the target company's landmarks when determining the position reference. However, if the divisionID filter is specified, then the service considers only those landmarks that either explicitly match the filter, or those landmarks that are applicable to all divisions.
Note also that if the supplied position coordinates fall inside the boundaries of a landmark, then a reference to that landmark will be returned regardless of that landmark's division.

PositionReference getPositionReference(String targetCompanyId, String divisionId, double latitude, double longitude) throws WSException

targetCompanyId: (optional) A string containing the unique identifier of the target company.
NOTE: If no targetCompanyId is specified, the company of the authorized user making the call will be used.
divisionId: (optional) A string containing the unique identifier of the division. This element should be left blank if not being used.
latitude: A floating point (double) value containing the latitude in decimal degrees. A positive value indicates the northern hemisphere. A negative value indicates the southern hemisphere.
longitude: A floating point (double) value containing the longitude in decimal degrees. A positive value indicates the eastern hemisphere. A negative value indicates the western hemisphere.

Authorization Requirements

The credentials supplied with this method call (as specified in the accompanying WS-Security header) must be authorized to the following application(s) and their associated role-based permissions.

Required Application Licenses
- Remote Integration

Required User Permissions
- Can use GeoServices

Customer integrators are authorized to their own company's data only.

Sample XML Request

Only the SOAP body is shown.

<soap:Body>

<getPositionReference>

<targetCompanyID>MYCOMPANY</targetCompanyID>

<divisionID>DFT</divisionID>

<latitude>40.15736100</latitude>

<longitude>-75.88157400</longitude>

</getPositionReference>

</soap:Body>

XML Response

Here is an example that shows what the Position Reference object will look like in XML.

<positionReference>

<distance>2.54<distance/>

<direction>NNE<direction/>

<placeName>CSDI<placeName/>

<placeAlias>Cornerstone Software<placeAlias/>

<placeAlias2/>

<placeAlias3/>

<placeAlias4/>

<placeAlias5/>

<placeType>Company Location<placeType/>

<city>Morgantown<city/>

<stateProv>PA<stateProv/>

<postal>19543<postal/>

<country>US<country/>

</positionReference>

Exceptions

001 Unknown Error
003 Company not authorized for integration.
004 User not authorized
005 User cannot retrieve details for specified company.
006 Invalid latitude/longitude values entered.
007 Latitude/longitude are outside of the range of data.
008 Invalid targetCompanyId entered
009 Invalid divisionId entered