Skip to main content
Omnitracs Knowledge Base

Return Places Near - OMPLCNER

Return Places Near (OMPLCNER) RI

Required Parameter Group:

1 Latitude Input Packed(7,0)
2 Longitude Input Packed(7,0)
3 Distance Limit Input Packed(3,0)
4 Number of Finds Limit Input Packed(3,0)
5 Direction to Look Input Char(4)
6 Place Type Filter #1 Input Char(5)
7 Place Attribute Filter #1 Input Char(10)
8 Place Type Filter #2 Input Char(5)
9 Place Attribute Filter #2 Input Char(10)
10 Place Type Filter #3 Input Char(5)
11 Place Attribute Filter #3 Input Char(10)
12 Place Type Filter #4 Input Char(5)
13 Place Attribute Filter #4 Input Char(10)
14 Place Type Filter #5 Input Char(5)
15 Place Attribute Filter #5 Input Char(10)
16 Return Status Output Char(1)
17 Return Place Array Output Char(4500)

API Overview:
The Return Places Near API (OMPLCNER) performs a 'places near' proximity request and returns an array of places to the calling program. The array returned is a list of places in 'closest first' order that are near some specified reference point. This API will select places based on the input parameters received.

Required Parameter Group Details:
(1) Latitude
INPUT; PACKED(7,0)
This parameter is the latitude portion of the reference point coordinate pair. This parameter must be given in signed seconds (not DDMMSS). This coordinate pair defines the geographic location from which the proximity search will begin.

(2) Longitude
INPUT; PACKED(7,0)
This parameter is the longitude portion of the reference point coordinate pair. This parameter must be given in signed seconds (not DDMMSS).

(3) Distance Limit
INPUT; PACKED(3,0)
This parameter limits the search to only those places that are within the specified radius. This value, which must be between 1 and 500, will be interpreted as either miles or kilometers depending on the system configuration.

(4) Number of Finds Limit
INPUT; PACKED(3,0)
This parameter, which must be between 1 and 100, limits the search to a maximum number of places.

(5) Direction to Look
INPUT; CHAR(4)
This parameter limits the search by controlling which geographic direction the system will check for close places. Valid values are:

*ALL All directions E East NW Northwest
N North W West SE Southeast
S South NE Northeast SW Southwest

(6) Place Type Filter #1
INPUT; CHAR(5)
This parameter allows the user to filter the list of close places by selecting specific place types. Up to five place types may be specified; if none are specified, then all types are selected.

(7) Place Attribute Filter #1
INPUT; CHAR(10)
This parameter allows the user to further refine the filtering criteria by specifying attributes for one or more of the place types. Each one of these Place Attribute Filter parameters may only be specified if, and only if, its corresponding place type was specified. If specified, these parameters must be formatted as an array of up to 10 place type attributes (ie. 'YYNYNNYNNN'). This 'attribute mask' will be used to filter the list of close places that are displayed to the user. The 10 Y/N flags correspond to the following list of attributes:

1. Company Location
2. Unloading Location
3. Loading Location
4. Trailer Drop
5. Intermodal Point
6. User Defined Attribute #1
7. User Defined Attribute #2
8. User Defined Attribute #3
9. User Defined Attribute #4
10. User Defined Attribute #5

(8) Place Type Filter #2
INPUT; CHAR(5)
Same as Place Type Filter #1.

(9) Place Attribute Filter #2
INPUT; CHAR(10)
Same as Place Attribute Filter #1.

(10) Place Type Filter #3
INPUT; CHAR(5)
Same as Place Type Filter #1.

(11) Place Attribute Filter #3
INPUT; CHAR(10)
Same as Place Attribute Filter #1.

(12) Place Type Filter #4
INPUT; CHAR(5)
Same as Place Type Filter #1.

(13) Place Attribute Filter #4
INPUT; CHAR(10)
Same as Place Attribute Filter #1.

(14) Place Type Filter #5
INPUT; CHAR(5)
Same as Place Type Filter #1.

(15) Place Attribute Filter #5
INPUT; CHAR(10)
Same as Place Attribute Filter #1.

(16) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:

0 Success, proximity search executed and one or more places were found
1 Success, proximity search executed but no places were found
2 Failure, error in one the passed parameters
3 Failure, undefined fatal error occurred
A Failure, API failed when called remotely

(17) Return Place Array
OUTPUT; CHAR(4500)
This parameter returns an array that contains 100 elements of 45 bytes in length. The first 100 places that meet the required search parameters will be returned in this array.

1-4500 Array of Places
Repeating blocks of 45 bytes each
Char(4500)

Array of Places

1-5 Distance from Reference Point(mls or kms) Zoned(5,1)
6-8 Direction from Reference Point Char(3
9-33 Place Name Char(24)
34-38 Place State & Country code Char(5
39-45 Place Identifier Zoned(7,0)
  • Was this article helpful?