Get Proximity Reference - OMGETPRX
Get Proximity Reference (OMGETPRX) RI
Required Parameter Group:
| 1 | Place Type | Input | Char(5) |
| 2 | Latitude | Input | Packed(7,0) |
| 3 | Longitude | Input | Packed(7,0) |
| 4 | Place Identifier to Exclude | Input | Packed(7,0) |
| 5 | Proximity Reference | Output | Char(256) |
| 6 | Return Status | Output | Char(1) |
API Overview:
The Get Proximity Reference API (OMGETPRX) returns a proximity reference for a given latitude/longitude pair. The returned proximity reference contains information regarding the nearest QTRACS place . A place is a point on the earth that has been pre-defined to the QTRACS place database. The distance and direction of the nearest place is returned to the calling application along with the associated name, state, postal code, and identifier of that place.
Each place is defined as a certain type, which may be CITY, TOWN, or one of many user-defined place types. The OMGETPRX function may be passed a place type which will limit the proximity search to those places of the specified type. In addition, the function will also accept a place identifier that will not be returned in the search.
Required Parameter Group Details:
(1) Place Type
INPUT; CHAR(5)
This parameter controls which types of places will be considered by the API when trying to determine the nearest place to return as the proximity reference. Valid values are:
| TOWN | Return a proximity reference to the nearest place of type TOWN (unless a City is closest) |
| CITY | Return a proximity reference to the nearest place of type CITY |
| ttttt | Return a proximity reference to the nearest place of the user defined type ttttt |
| *QUIT | Remove program from memory and return control to calling application |
(2) Latitude
INPUT; PACKED(7,0)
This parameter is the latitude, given in total signed seconds, of the point to which the proximity reference should be calculated.
(3) Longitude
INPUT; PACKED(7,0)
This parameter is the longitude, given in total signed seconds, of the point to which the proximity reference should be calculated.
(4) Place Identifier to Exclude
INPUT; PACKED(7,0)
This parameter contains the place identifier of a place that should be excluded from the proximity search. This parameter is useful when passing a latitude/longitude to the function that is known to be a defined place. By passing the exclude place identifier, the API will return the place closest to it, but not that place itself.
(5) Proximity Reference
OUTPUT; CHAR(256)
This parameter is a fixed format data structure that contains the elements of the proximity reference, as well as the identifier of the referenced place. The identifier may be used to retrieve additional data regarding the referenced place. The information returned is described in the following table.
| 1-25 | Place Name (upper case) | Char(25) |
| 26-50 | Place City (mixed case) | Char(25) |
| 51-52 | Place State | Char(2) |
| 53-61 | Place Postal Code | Char(9) |
| 62-66 | Distance to Place | Zoned(5,1) |
| 67-69 | Distance Units (displayable text) | Char(3) |
| 70-72 | Direction to Place (displayable text) | Char(3) |
| 73-77 | Place Type | Char(5) |
| 78-84 | Place Identifier | Zoned(7,0) |
| 85-94 | Place Alias | Char(10) |
| 95-256 | Reserved | Char(162) |
(6) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Failure, proximity reference cannot be resolved |
| 1 | Success, proximity found |
| A | Failure, API failed when called remotely |