Syntax 

int PCMSLookup(Trip trip, const char *placeName, int option)

Parameters

Trip trip – Handle to a trip.

const char *placeName – A place name in any format acceptable to PC*MILER. Input may contain an asterisk (e.g. “PRI*, NJ”) or be in the form of latitude/longitude points or any custom place name created in PC*MILER.  Matches will also be returned if your input is either a fragment or matches multiple cities with the same name (e.g. a city with many different ZIP codes).

int option – The input value affects the output returned as follows:

• Option = 0 – Returns the number of matches found (of any confidence level), or 0 if no matches are found. This option is provided for the benefit of users who are implementing pick list functionality, who would then call PCMSGetMatch to get each item for their pick list. The first match in the list (match index 0) will be the default or best match. Lists for U.S. cities will start with the default or central city ZIP code, then continue with a numeric sort of the cities’ remaining ZIP codes, with matches that have no ZIP codes sorted alphabetically at the bottom. With the optional Canadian Postal Code data add-on, the first match will be the city and province code alone then an alphanumeric sort of the postal codes for that city.

• Option = 1 – Returns one exact match (confidence level 1), or an error if no exact match is found. Can return a pick list.

• Option = 2 – Returns one exact match, or one fair match (confidence level 2) if no exact match is found; or an error if no exact or fair matches are found. A fair match is a close match to the user’s input address, subject to a minimum trust percentage of 85%, an out-of-range test, and a multiple matches rule. The trust percentage measures how closely the text of the match resembles the text of the user’s input. The out-of-range test checks that the match’s address range is within 500 address units of the user’s input address number. The multiple matches rule checks that alternative exact or fair matches, if any, are within .5 miles of one another.

• Option = 3 – Use this option for addresses. Returns one exact match (confidence level 1) or an error if no exact match is found. (A license for PC*MILER|Streets is required.)

• Option = 5 – Returns one exact match (confidence level 1), or extended error code if no exact match is found. Can return a pick list.

NOTE:  The .INI settings and API that pertain to Mexican postal codes affect options 1 and 5 but do not have any effect when option 0 or 2 is passed.

Description

Creates a list of cities that match your input. You can then check each item in the list yourself for a matching name, or pop up the list in your own list box.

Return Values 

Returns the number of cities that match your input.

Sample Code 

\* Lookup all cities that match *\
matches = PCMSLookup(trip, "PRI*, NJ", 0);
printf ("%d matching cities to 'PRI*, NJ'\n", matches);

\* Show all the matching cities. Note: You could use variable ‘matches’ below instead, since PCMSNumMatches() == matches.*\
for (i = 0; i < PCMSNumMatches(trip); i++)
{
            PCMSGetMatch(trip, i, buffer, 25);
            printf ("[%s]\n", buffer);

Supported Since: PC*MILER|Connect 12

Category: Geocoding