Geostan v34 00 Reference Manual
Geostan v34 00 Reference Manual
Version 34.0.0
Precisely is a wholly-owned subsidiary of Syncsort Incorporated. See www.precisely.com for information about our
valuable trademarks.
The following trademarks are owned by the United States Postal Service®: CASS, CASS Certified, DPV, eLOT,
FASTforward, First-Class Mail, Intelligent Mail, LACSLink, NCOALink, PAVE, PLANET Code, Postal Service,
POSTNET, Post Office, RDI, SuiteLink, United States Postal Service, Standard Mail, United States Post Office, USPS,
ZIP Code, and ZIP+4. This list is not exhaustive of the trademarks belonging to the Postal Service.
USPS Notice: Precisely holds a nonexclusive license to publish and sell ZIP+4 databases on optical and magnetic
media. The price of the Precisely product is neither established, controlled, nor approved by the U.S. Postal Service.
Precisely is a non-exclusive licensee of USPS® for NCOALink® processing. Prices for the Precisely products, options
and services are not established, controlled or approved by USPS® or United States Government. When utilizing RDI™
data to determine parcel-shipping costs, the business decision on which parcel delivery company to use is not made by
the USPS® or United States Government.
Spectrum Geocoding Datasets used within Precisely applications are protected by various trademarks and by one or
more of the following copyrights:
© 2021 TomTom. All rights reserved. This material is proprietary and the subject of copyright protection and other
intellectual property rights owned by or licensed to TomTom or its suppliers. The use of this material is subject to the
terms of a license agreement. Any unauthorized copying or disclosure of this material will lead to criminal and civil
liabilities.
© 2021 HERE
The Master Location Data (MLD) product is a produced work that referenced the Microsoft US Building Footprints
dataset. This dataset is available at https://github.com/Microsoft/USBuildingFootprints and is licensed under the Open
Database License (ODbL). The license is available at https://opendatacommons.org/licenses/odbl/.
1 – Before You Begin
In this chapter
This chapter discusses the purpose and use of this guide, and how to
obtain assistance from Precisely.
Purpose of this guide 6
If you need more help 6
To obtain additional user guides 6
Purpose of this guide
Welcome to GeoStan. This guide provides information on using the GeoStan library, along
with the sample applications Geotest and Geocoder. Besides providing information on how
to use GeoStan functions, this guide also provides information on several USPS standards
and policies.
The Website
You can also find out about Precisely software products and services on our website:
https://www.precisely.com.
In this chapter
About GeoStan 8
Supported languages 8
Installation requirements 9
Installing GeoStan 10
Configuring GeoStan 10
Initializing GeoStan 15
About GeoStan
This manual details the use and functionality of GeoStan. These functions may be in the
form of a library, DLL, or copybook depending on the platform you are developing on. The
functions allow the developer to incorporate national address standardization, as well as
address and ZIP centroid geocoding into virtually any application.
The process of standardizing and geocoding an address is very straightforward using these
functions and gives the developer a large amount of freedom in implementing the user
interface.
A standardized address contains the street address, city, state, and complete ZIP+4,
corrected to USPS standards. A geocoded address contains the address as found in the
geocode database, as well as items such as the Latitude, Longitude, and Census Block. A
detailed match code is also returned for each process.
GeoStan uses data from two primary sources to perform its functions: a street network
database, acquired from one of several premium vendors or the U.S. Census Bureau, and
the U.S. Postal Service ZIP+4 Directory files. To fully understand the capabilities of
GeoStan and the data elements that GeoStan returns, it is important to understand these
underlying file types. Precisely suggests you familiarize yourself with the content of these
source files.
For information about TIGER files, contact the U.S. Census Bureau and request the TIGER
Technical Documentation. Information regarding street network data from premium vendors
is available at the vendor’s Website. For information about the ZIP+4 Directory file, contact
the USPS National Customer Support Center at 1-800-238-3150 and request the Address
Information System Products Technical Guide.
Supported languages
GeoStan includes the following API libraries, click the linked item next to each one for more
information:
• C - Chapter 4 Defining C functions
• COBOL - Chapter 5 Defining COBOL procedures
• Java - Chapter 6 Java quick reference
• .Net - Chapter 7 .Net quick reference
HP-UX 32-bit
HP-UX 64-bit
Note: To see a detailed list of the officially supported OS versions, see the GeoStan Suite
Supported Platforms document available at support.precisely.com.
Precisely distributes GeoStan as Windows DLL files and as UNIX C libraries. The following
table lists the filenames for the Windows DLL and UNIX libraries.
Platform Filename
The following table lists the APIs supported on each operating system.
Windows
UNIX
z/OS
Configuring GeoStan
The following sections provide information on configuring GeoStan for different platforms
and include the following topics:
• Understanding the symbolic constants of GeoStan
• Using GeoStan on Windows
• Using GeoStan on UNIX
• Using GeoStan on z/OS
Note: Beginning with GeoStan v25.0, Solaris applications must also link with the system
library libsocket.so.
See the sample make files included as part of the installation for the libraries needed for
your system.
GSDFILE* Input Y First GSD file loaded by GeoStan. If you are using multiple GSD files,
you must use this DD Name for the first file.
GSIFILE Input N First alias file loaded by GeoStan. If you are using multiple gsi files, you
must use this DD Name for the first file.
GSIFILxx Input N Additional alias files loaded by GeoStan. The first file must use
GSIFILE for correct processing. Additional files must be in sequential
order (01, 02, 03..). If the files are not in sequential order, GeoStan will
not read the files after the first blank GSIFILxx file.
ZIPCENT Input N CICS platform specific; used for Expanded Search and MLD
processing
EWSFILE Input C Valid, unexpired EWS file ews.txt; see “Understanding Early
Warning System (EWS)” on page 78.
GSLFILE Input C eLOT and Z4Change data file us.gsl
CEEDUMP Output N Data set for error messages generated by Language Environment
Dump Services. Must be a sequential data set and must be allocated
to SYSOUT, a terminal, or a unit record device; or the data set must
have the attributes RECFM=VBA, LRECL=125, and BLKSIZE=882.
SYSERR Output N Alternate output for some C++ programs. Not required unless
SYSPRINT and SYSTERM are missing.
SYSPRINT Output N Data set for listings and diagnostics from the user program.
LRECL=137, RECFM=VBA, and BLKSIZE=882.
SYSTERM Output N Alternate output for some C++ programs. Not required unless
SYSPRINT is missing.
In this chapter
This chapter provides the following information on the concepts used
by GeoStan.
Getting started 17
Finding an address 18
Using GeoStan match modes 24
Address matching 26
Using enhanced search options 40
Using geocoding features 54
Using Master Location Data 63
Using USPS matching enhancements 76
Elements available via GeoStan 80
Using custom supplemental data sets 81
Using reverse geocoding 82
Using reverse APN matching 85
Getting started
Detailed below is an introduction to running GeoStan. See the following topics for more
information:
• Get and set functions
• Basic use of GeoStan
• Optimization issues
Basic matching
Once GeoStan initializes, there are many options available through the GeoStan functions
to allow diverse implementations of matching strategies. A basic approach is outlined
below:
1. Construct initialization properties.
Samples
Refer to the sample code provided in the installation directory as follows:
Windows:
\Geolib\Ms_c
UNIX:
<install directory>/samples
where <install directory> is the user-specified directory to which the tar file was
extracted.
Optimization issues
Precisely designed and developed the GeoStan data format and functions to allow you to
directly access from your internet download or DVD. However this design is most effective
when you process records in State plus City order, or in ZIP Code order.
Finding an address
GeoStan processing modes and options are used to determine how address searches are
performed and to specify the placement of the geocodes returned.
In some cases, GeoStan cannot determine which match candidate is the best match. In
these instances, GeoStan returns a status indicating multiple candidates for a match for you
to determine which is the appropriate candidate.
For more information on matching addresses, see the following topics:
• Entering an address
• Understanding the typical address
• Understanding how GeoStan processes addresses
Entering an address
For optimal performance and match rates, input an address free of misspellings and with all
known address components. If you are using GeoStan for mailable address
standardization, to obtain the highest match rate, verify that your input follows USPS
standards.
GeoStan accepts many input fields that make up an address. Ensure that your input
address contains a street address line and a last line, or a single line with both address and
last line elements. These inputs help ensure that GeoStan can accurately identify a location
area in which to search for a match candidate based on the city, state, and ZIP Code.
GeoStan can also perform address matching with only a city in the input lastline; however,
certain restrictions do apply - for more information, see “City-only lastline matching” on
page 29.
GeoStan also accepts a street address line with individual city, state, and ZIP Code fields
instead of a last line. Use this type of input configuration if you are confident that you have a
complete address list; free of misspellings and incomplete addresses.
If you are using GeoStan for address standardization or geocoding, GeoStan requires
addresses to have at least a street name, and either a city or a ZIP Code to obtain a match
and a geocode. The addition of a state will help resolve multiple matches if only entering a
city, but it is not required.
Element Description
Firm Name Optional. You can configure GeoStan to match the input firm name, or
business name, rather than an address.
Street Address Line Contains the street address. GeoStan recognizes the following types of
street addresses:
• PO Box, such as PO Box 100
• Rural Route or Highway Contract address
• General Delivery (stated in the address line)
• Street, such as 4750 WALNUT ST
• Highrise that contains unit information, such as 4750 WALNUT ST
STE 200
• Building name where it matches the firm name in the ZIP+4
database. See enhanced search options.
These types of street addresses can have all or some of the following
elements:
• House Number
• Predirectional, such as N, NE, and S
• Street Name
• Street Type, such as Ave, Blvd and Pkwy
• Postdirectional, such as N, NE, and S
• Unit Type, such as Apt, Ste, and Bldg
• Unit Number
• Private Mail Box
Last Line Contains the location of the address. GeoStan can recognize the
following last line elements:
• City
• State
• ZIP Code
• ZIP + 4 Code
GeoStan also recognizes the elements on individual input lines when matching in multiline
mode.
Match code Information about the match of the input address to the
reference data
Result code GeoStan returns a result code for every record it attempts to
match.
Street Parity The side of the street on which the match resides.
Range Parity The parity of the house number in the range: even, odd, or
both.
Note: GeoStan does not respect the range parity when processing in Relaxed or
Interactive modes.
Hyphenated addresses
GeoStan handles hyphens in address ranges. Address ranges are checked for missing or
misplaced hyphens. Alpha-numeric ranges are checked for proper sequence.
If a house number is incorrectly entered with a hyphen, the number is first concatenated. If
no match is resolved, GeoStan tries the section of the house number following the hyphen
as a unit number. See “Matching address ranges” on page 50 for special processing of
hyphens.
Mode Description
Exact Requires a very tight match. This restrictive mode generates the fewest match
candidates, which decreases the processing time. When using this mode, ensure
that your input is very clean; free of misspellings and incomplete addresses.
Close Default. Requires a close match and generates a moderate number of match
candidates.
CASS Imposes additional rules to ensure compliance with the USPS CASS regulations.
The purpose of this match mode is to create mailable addresses for USPS mailing
discounts. Use this mode to standardize your input for mailing. This mode generates
a large number of match candidates.
CASS mode deviates from the other modes in its processing. This mode does not
perform intersection, building name, or spatial alias (TIGER, TomTom, HERE
street name alias or Centrus alias) or matches to User Dictionaries or auxiliary
files. It does not match to candidates from data sources that do not have USPS
equivalent records. This mode recognizes and parses two unit numbers on the
same address line, for example a building and unit number.
Relaxed Allows a loose match and generates the most match candidates, which increases
the processing time and results in more multiple matches. Use this mode if you are
not confident that your input is clean; free of misspellings and incomplete addresses.
This mode recognizes and parses two unit numbers on the same address line, for
example a building and unit number. This is mode does not respect the range parity
when making an address match.
Interactive Available in single-line address matching only. This mode is designed to better
handle the specific matching challenges presented by interactive matching.
Interactive mode permits for more flexible matching patterns and may, in some
cases, return additional possible matches than relaxed match mode. This mode
recognizes and parses two unit numbers on the same address line, for example a
building and unit number. This is mode does not respect the range parity when
making an address match.
Custom Allows applications to specify individual "must match" field matching rules for
address number, addressline, city, Zip Code, state.
Note: Match modes are only used in forward geocoding; the match mode setting is ignored
in reverse geocoding.
HIGHLAND VIEW WINCHESTER 01890 5 HIGHLAND VIEW AVE, 5 HIGHLAND VIEW AVE,
WINCHESTER, MA 01890 WINCHESTER, MA 01890
5 HIGHLAND TER,
WINCHESTER, MA 01890
5 HIGHLAND AVE,
WINCHESTER, MA 01890
414 PINE WILLIAMSFIELD 61489 414 N PINE ST, 414 N PINE ST,
WILLIMAMSFIELD, IL 61849 WILLIMAMSFIELD, IL 61849
414 PINE ST,
WILLIAMSFIELD, IL 61489
611 W 13TH JOPLIN MO 64801 611 E 13TH ST, 611 W 13TH ST,
(conflict between directional and ZIP Code) JOPLIN, MO 64801 JOPLIN, MO 64804
611 W 13TH ST,
JOPLIN, MO 64804
Address matching
GeoStan provides support for several variations in the format of an input address. This
section contains information on the following topics:
• Multi-line matching
• Two-line matching
• Matching dual addresses
• Single-line address matching
• City name matching
• City-only lastline matching
• Match rate and performance
• Analyzing a match - Status return codes
• Understanding Extended Match Codes
Note: For users of Master Location Data, additional options are available. See “Using
Master Location Data” on page 63.
Multi-line matching
Multi-line matching allows you to pass any six lines of address information to GeoStan to
extract and standardize the address. To specify multi-line matching, use the following:
COBOL Set the GSOPTIONS argument in GSDATSET to any of the GS-LINEX variables.
JAVA Set the element argument in setData to any of the LINEX fields of the
GeoStanBase class.
.NET Set the element argument in setData to any of the GS_LINEX fields of the
GeoStan class.
Note: Do not mix the two-line address input enums with the multi-line address input enums.
GeoStan executes a two-line search if you use the two-line address input enums and
ignores the multi-line enums.
blank (GS_LINE5)
blank (GS_LINE6)
GeoStan takes the valid address components from GS_LINE2 and GS_LINE4 and outputs the
invalid values in GS_LINE1 and GS_LINE3.
Note: GeoStan does not perform dual address matching on multi-line addresses.
Two-line matching
Two-line address matching allows you to pass two different address lines to GeoStan.
GeoStan scans these two lines and extracts and standardizes a two-line address.
COBOL Use the GS-ADDRLINE and GS-ADDR2 variables in the GSOPTIONS parameter of
GSDATSET.
JAVA Use the ADDRLINE and ADDR2 fields of the GeoStanBase class in the element
argument in setData.
.NET Use the GS_ADDRLINE and GS_ADDR2 fields of the GeoStan class in the
element argument in setData.
Note: Do not mix the two-line address input enums with the multi-line address input enums.
GeoStan executes a two-line search if you use the two-line address input enums and
ignores the multi-line enums.
If a unit designator is present on one address line and a valid address appears on the other
line, GeoStan appends the unit information to the address.
If you do not specify a preference for a P.O. Box or a street address, GeoStan uses the
value in the first line of the address as the preferred input. For more information on setting
these preferences see “Specifying a preference for street name or P.O. Box” on page 41.
JAVA Use the ADDRLINE fields of the GeoStanBase class in the element argument in
setData.
.NET Use the GS_ADDRLINE fields of the GeoStan class in the element argument in
setData.
Restrictions:
• City-only lastline input matching is not supported in CASS mode.
• City-only lastline is not supported when matching to User Dictionaries.
• When matching using city-only lastline, the GS_FIND_PREFER_ZIP_OVER_CITY setting is
ignored.
Percentage of
Input address records matched
format Match mode (%) Time (s)
The geocoding process executes more quickly and efficiently with input records that are
free of misspellings and with all known address components.
Match mode
The match mode can affect match rates and performance. Assuming real-world data
(imperfect input records), the match modes compare to one another as follows:
• Exact: Performs fastest with the lowest match rate.
• Close: Executes relatively fast with very good match rates.
• Relax: Performs slower than Close mode, but with higher match rates; however, there
is a greater possibility that false-positive matches are returned in this mode.
Data sets
The number of loaded data sets may impact performance: the more data sets in use could
lengthen the geocoding processing time.
Output data
There are 100+ pieces of information that can be queried after performing a successful
geocode operation, e.g., latitude, longitude, etc. The more queries performed for each
record, the slower the overall geocoding rate.
Extended
Input Addressline Output Addressline Code Description
4750 WALNUT ST STE 200 4750 WALNUT ST STE 200 0 Matched on all address
information on line, including
Unit Number and Unit Type if
included.
4750 WALNUT ST C/O JOE SMITH 4750 WALNUT ST 1 Matched on Unit Number and
Unit Type if included. Extra
information on address line
ignored. Extra information not
considered for matching moved
to GS_ADDR2 or
GS_MAIL_STOP field.
4750 WALNUT ST UNIT 200 4750 WALNUT ST STE 200 2 Matched on Unit Number. Unit
Type changed.
4750 WALNUT ST UNIT 200 C/O JOE SMITH 4750 WALNUT ST STE 200 3 Matched on Unit Number. Unit
Type changed. Extra
information on address line
ignored. Extra information not
considered for matching moved
to GS_ADDR2 or
GS_MAIL_STOP field.
4750 WALNUT ST STE 2-00 4750 WALNUT ST STE 200 4 Unit Number changed or
ignored.
4750 WALNUT ST STE 2-00 C/O JOE SMITH 4750 WALNUT ST STE 200 5 Unit Number changed or
ignored. Extra information on
address line ignored. Extra
information not considered for
matching moved to GS_ADDR2
or GS_MAIL_STOP field.
4750 WALNUT ST STE 400 4750 WALNUT ST STE 400 6 Unit Number changed or
ignored. Unit Type changed or
ignored. In this example, Suite
400 is not valid for the input
address, but the address match
is not prevented because of an
invalid unit number.
4750 WALNUT ST UNIT 2-00 C/O JOE SMITH 4750 WALNUT ST STE 200 7 Unit Number changed or
ignored. Unit Type changed or
ignored. Extra information on
address line ignored. Extra
information not considered for
matching moved to GS_ADDR2
or GS_MAIL_STOP field.
47-50 WALNUT ST STE 200 4750 WALNUT ST STE 200 8 Matched on Unit Number and
Unit Type if included. House
number changed or ignored.
47-50 WALNUT ST STE 200 C/O JOE SMITH 4750 WALNUT ST STE 200 9 Matched on Unit Number and
Unit Type if included. House
number changed or ignored.
Extra information not
considered for matching moved
to GS_ADDR2 or
GS_MAIL_STOP field.
47-50 WALNUT ST UNIT 200 4750 WALNUT ST STE 200 A Matched on Unit Number. Unit
Type changed. House Number
changed or ignored.
47-50 WALNUT ST UNIT 200 C/O JOE SMITH 4750 WALNUT ST STE 200 B Matched on Unit Number. Unit
Type changed. House Number
changed or ignored. Extra
information on address line
ignored. Extra information not
considered for matching moved
to GS_ADDR2or
GS_MAIL_STOP field.
47-50 WALNUT ST STE 20-0 4750 WALNUT ST STE 200 C House Number changed or
ignored. Unit Number changed
or ignored.
47-50 WALNUT ST STE 20-0 C/O JOE SMITH 4750 WALNUT ST STE 200 D House Number changed or
ignored. Unit Number changed
or ignored. Extra information on
address line ignored. Extra
information not considered for
matching moved to GS_ADDR2
or GS_MAIL_STOP field.
47-50 WALNUT ST UNIT 20-0 4750 WALNUT ST STE 200 E House Number changed or
ignored. Unit Number changed
or ignored. Unit Type changed
or ignored.
47-50 WALNUT ST UNIT 2-00 C/O JOE SMITH 4750 WALNUT ST STE 200 F House Number changed or
ignored. Unit Number changed
or ignored. Unit Type changed
or ignored. Extra information on
address line ignored. Extra
information not considered for
matching moved to GS_ADDR2
or GS_MAIL_STOP field.
To enable Extended Match Codes, use the information in the following table that is
appropriate for your API:
Note: For information on returned match codes see “Definitions for Extended Match Code
(3rd hex digit) values” on page 470.
#define GEOSTAN_PROPERTIES
/* DPV properties */
GsPropSetBool( &initProps, GS_INIT_DPV, TRUE );
GsPropSetLong( &initProps, GS_INIT_DPV_DATA_ACCESS,
DPV_DATA_FULL_FILEIO );
GsPropSetStr( &initProps, GS_INIT_DPV_DIRECTORY,
"\\\\cog1nas1\\Current\\LinkDPV" );
GsPropSetStr( &initProps, GS_INIT_DPV_SECURITYKEY,
"C51F-02Z7-7906-Q9BG" );
/* LACS properties */
GsPropSetBool( &initProps, GS_INIT_LACSLINK, TRUE );
GsPropSetStr( &initProps, GS_INIT_LACSLINK_DIRECTORY,
"\\\\cog1nas1\\Current\\LinkLACSLink" );
GsPropSetStr( &initProps, GS_INIT_LACSLINK_SECURITY_KEY,
"740F-05L2-A791-51D7" );
if (gs == 0) {
} else {
GsClear(gs);
GsDataSet(gs, GS_ADDRLINE, addresses[i][0]);
GsDataSet(gs, GS_LASTLINE, addresses[i][1]);
printf("\n***********************************************\n");
printf("match code: %s\nlocation code: %s\naddress:
%s\nlastline: %s\nlongitude: %lf\nlatitude: %lf",
matchcode, loccode, address, lastline,
(double)(atof(longitude)/1000000.0),
(double)(atof(latitude)/1000000.0));
printf(
"\n***********************************************\n\n");
fflush(stdout);
break;
case GS_ERROR:/* Each error can be handled */
case GS_ADDRESS_NOT_FOUND:
case GS_ADDRESS_NOT_RESOLVED:
case GS_LASTLINE_NOT_FOUND:
default: /* or just the default */
iNumFailed++;
fprintf(stderr, "Error geocoding address.\n");
}
}
/* Terminate GeoStan */
GsTerm (gs);
}
/* summary report */
printf( "\nSummary of matches: \n");
printf( " Total addresses: %d\n", numAddresses );
printf( " Matched: %d\n", iNumMatched );
printf( " Failed: %d\n\n", iNumFailed );
return 0;
}
If GeoStan cannot match to the preferred address, it tries to match to the alternative
address.
The following example uses the C Language.
If you set the GS_FIND_PREFER_POBOX find property used with GsFindWithProps, and the input
address is
GeoStan first attempts to match to P.O. Box 24. If GeoStan cannot find a match, it then
attempts to match to 123 Main St.
Note: GeoStan ignores the address preference if processing in CASS mode.
If you do not specify a preference for a P.O. Box or street address, GeoStan attempts to
match to the first address line it receives as input.
Implementation
Note: It does not matter what you name the files on the mainframe as long as the
DD statements point to it.
C GS_STATUS_FILE_POI_IDX
COBOL GS-STATUS-FILE-POI-IDX
JAVA STATUS_FILE_POI_IDX
.NET GS_STATUS_FILE_POI_IDX
3. Set the GS_FIND_BUILDING_SEARCH find property to true. The POI Index file will
automatically be searched when the GS_FIND_BUILDING_SEARCH find option is enabled
and a firm, building or POI name is specified in the address line.
4. Process the match by calling the Find Properties function.
If an alias match is made to the POI Index file, the return value is as follows:
Implementation
Note: It does not matter what you name the files on the mainframe as long as the
DD statements point to it.
2. To confirm the ppoi1.gsi, ppoi2.gsi, and ppoi3.gsi loaded successfully, query the Status
File POI Index status output property. Boolean. True = file loaded successfully. Default
= False.
C GS_STATUS_FILE_PREMIUM_POI_IDX
COBOL GS-STATUS-FILE-PREMIUM_POI-IDX
JAVA STATUS_FILE_PREMIUM_POI_IDX
.NET GS_STATUS_FILE_PREMIUM_POI_IDX
3. Set the GS_FIND_BUILDING_SEARCH find property to true. The Premium POI Index file will
automatically be searched when the GS_FIND_BUILDING_SEARCH find option is enabled
and a firm, building or POI name is specified in the address line.
4. Process the match by calling the Find Properties function.
If an alias match is made to the Premium POI Index file, the return value is as follows:
DOWNERS GROVE LL
Returns LASTLINE=DOWNERS GROVE LL,
No ZIP Code for correction
DOWNRS GROVE, LL
Returns LASTLINE=DOWNRS GROVE, LL
No ZIP Code for correction
LILSE ILLINOIS
Returns LASTLINE= LISLE, IL 60532
Correct spelled out state
LISLE ILLINOS
Returns LASTLINE= LISLE ILLINOS
Incorrect spelled out state, no ZIP Code for correction
Note: For information on the returned match codes, see “Correct lastline match codes” on
page 473.
The Address Range match is to a single street segment, with the geocode being placed on
the mid-point of the range.
Input: 47-50 Walnut St, Boulder, CO
Output: 4750 Walnut St, Boulder, CO
In the example below, the second number is not larger than the first, so GeoStan treats this
as a unit number rather than a ranged address:
Input: 4750-200 Walnut St, Boulder, CO
Output: 4750 Walnut St STE 200, Boulder, CO
Offset • Address
Ensures the point does not reside in the middle of a street. Moves • Reverse Geocoding
the point perpendicular to the portion of the street segment in
which it lands by the value you specify. The default is 50 feet for
the best visual representation for mapping packages.
Squeeze • Address
Ensures the point does not reside in an intersection or too close to • Reverse Geocoding
the end of a street. Using a squeeze distance moves both street
end points closer to the center of the segment by the value you
indicate.
Point-level matching locates the center of the actual building footprint or parcel. This is the
most accurate type of geocode and is used in industries such as internet mapping, flood
hazard determination, property and casualty insurance, telecommunications, and utilities.
If you are licensed for the point-level data option, you do not need to execute any additional
initialization or setup after you have installed the point-level data. GeoStan automatically
processes your address lists through the point-level data.
When processing address lists, GeoStan first searches for a match in the point-level data. If
it cannot find an exact match in the point-level data, GeoStan continues searching for a
better match in the street network data. GeoStan returns the best match found, with
preference given to matches from the point-level dataset.
Note: For users of Master Location Data, additional options are available. See “Using
Master Location Data” on page 63.
In the occasional scenario, if there is a situation where the boundaries found have the same
parity but are on opposite sides of the street. To determine on which side of the street the
address should be, address point interpolation uses information from the matched street
segment.
Note: Also see “Using User Dictionaries with address point interpolation” on page 507.
Segment parity
The segment parity describes which side of the street has the odd house numbers relative
to the segment’s starting latitude/longitude coordinates, as follows:
• L/Left/1 = odd house numbers are on the left side of the street and even house
numbers are on the right.
• R/Right/2 = odd house numbers are on the right side of the street and even house
numbers are on the left.
• B/Both/0 = odd and even house numbers are on both the left and the right sides of
the street (interpolated point is always on the segment).
Segment direction
The segment direction describes if the house numbers increase or decrease from the
starting latitude/longitude coordinates to the ending latitude/longitude coordinates of the
segment.
• F/Forward/1 = house numbers increase.
• R/Reverse/0 = house numbers decrease.
Valid City City (GM). City, County, and State are all valid.
Valid County
Valid State
Troy, Rensselaer, NY
Invalid City County (GC) There is no city of San Diego in NY. However, there is an Albany County in
Valid County NY, so County is the best possible match.
Valid State
San Diego, Albany, NY
Invalid City State (GS). There is no city of Phoenix in NY, nor is there a Maricopa County in NY, so
Invalid County State is the best possible match.
Valid State
Phoenix, Maricopa, NY
Valid City City (GM). There is a city of Albany in NY. There is a Saratoga County in NY, but Albany
Invalid County is not in that county. However, the city match is still made.
Valid State
Albany, Saratoga, NY
Valid Major City City (GM). There are approximately 300 U.S. cities recognized as a major city and can
Chicago be geocoded to the city centroid with no other information provided.
Valid City Seven matched candidates. The city of Albany, NY is a close match (GM). Five instances
No County of cities in New York that "sound like" Albany (such as Albion) are non-close GM matches.
The state centroid (GS) is also a non-close match.
Valid State
Albany, NY
Valid City No matched candidates. Since the state (LA) is missing, only a city match can be
Valid County attempted. Since Iberia is not recognized as one of the Major U.S. Cities, no match is
possible.
No State
Iberia, New Iberia
Invalid City Three matched candidates. The state centroid (GS) is a close match and two city
No County centroids (GM) are non-close "sound like" matches in New York State. If the input contains
a state, all matches must be within that state.
Valid State
St. Louis, NY
No City Two matched candidates. The county centroid (GC) is a close match and the state
Valid County centroid (GM) is a non-close match (GM).
Valid State
Otsego, NY
No City No matched candidates. A county name alone is not enough for a match.
Valid County
No State
Otsego
Valid City No matched candidates. A city name alone is not enough for a match, except if it is one
No County of the recognized Major U.S. Cities.
No State
Saco
The PreciselyID unique identifier serves as a lookup key with Precisely GeoEnrichment
data sets to add attribute data for an address location. Depending on the GeoEnrichment
data set(s) you install, the attribute data can include property ownership, real estate,
census, consumer expenditure, demographic, geographic, fire and flood protection, and/or
telecommunication and wireless systems information and more. Some of these data sets
return point location specific data, such as property ownership and real estate, whereas
others provide polygonal-based data, for example, fire and flood protection, which can
identify flood plains, wildfire or rating territories.
To ensure the latest address information and most accurate locations are being used,
businesses may regularly geocode their customer address list. There is a cost in terms of
computing power to this intensive process, as well as a small chance of changes to the
address match. Some businesses monitor these changes since it's integral to their
business. Additionally, many businesses have multiple address databases across different
business functions, and have the need for consistent representation of a single address
across multiple systems and databases. The Reverse PreciselyID Lookup feature removes
the need to re-geocode the address by using the PreciselyID unique identifier rather than
the address as input. The address together with latitude/longitude coordinates are returned.
The Reverse PreciselyID Lookup process is substantially faster and therefore less costly
than using the address to retrieve this information. In addition, since a PreciselyID is
persistent, there is no chance of matching to a different address.
The GeoEnrichment Fabric products are a variety of text-based data files that contain
different attributes for each address in the Master Location Dataset. You can use the
attributes in one or more of these GeoEnrichment data sets to identify customers for
products or services based on those specific attributes. The lookup key for these products
is the PreciselyID unique identifier rather than the address. This allows you to easily link
customers across multiple data sets if you need to consider attributes included in more than
one GeoEnrichment data set. For example, using Ground View Family Demographics
Fabric, in conjunction with Property Attribute Fabric, you would be able to generate a list of
PreciselyIDs for records that represent young families, with 4 or more persons, in large
houses, to target for specific products and services. Once records with the desired
attributes have been identified, the PreciselyIDs from those records can be used to return
the address and location information for those customers using PreciselyID Reverse
Lookup.
Implementation
C GS_INIT_OPTIONS_ZIP_PBKEYS
COBOL GS-INIT-OPTIONS-ZIP-PBKEYS
JAVA INIT_OPTIONS_ZIP_PBKEYS
.NET GS_INIT_OPTIONS_ZIP_PBKEYS
C GS_STATUS_FILE_ZIP_PBKEYS
COBOL GS-STATUS-FILE-ZIP-PBKEYS
JAVA STATUS_FILE_ZIP_PBKEYS
.NET GS_STATUS_FILE_ZIP_PBKEYS
4. Set the GS_FIND_Z_CODE find property to True. If this is not enabled, an "E" location code
is returned and the results data will not include a geocode nor PreciselyID.
5. Process the match by calling the Find Properties function.
Expanded Centroids
In some cases, more than one point-level geocode is available for an address matched in
Master Location Data (for more information on the different types of point-level geocodes,
see the "APnn" definitions in “Address location codes” on page 476). When more than one
point-level geocode is available from MLD data, only the highest quality geocode is
returned with the matched address returns using GsFindWithProps.
The Expanded Centroids feature is available with MLD and the optional Master Location
Structure Centroid Data Set (MLDB). If an address match is found in MLD, and MLDB is
loaded, GeoStan will search MLDB for additional geocodes for the matched address. If
additional geocodes are found for the matched address, these can be returned using
GsMultipleGet. The returned location code for an Expanded Centroids match will have an
"APnn" value with a data type of “MASTER LOCATION” and a GS_IS_ALIAS return value of
"A14".
When initializing GeoStan, include the Status File Expanded Centroids property to confirm
the us_cent.gsc file, which is a file in the Master Location Structure Centroid Data Set,
loaded successfully. This property is defined for each API in the following table:
C GS_STATUS_FILE_EXP_CENTROIDS
COBOL GS-STATUS-FILE-EXP-CENTROIDS
JAVA STATUS_FILE_EXP_CENTROIDS
.NET GS_STATUS_FILE_EXP_CENTROIDS
Requirements
The following is required to return data from the MLD Extended Attributes data set:
• Master Location Dataset (.gsd and .gsi files).
• Streets data set.
• MLD Extended Attributes data set (extatt*p.dld files).
• It is recommended that the vintages of the MLD and MLD Extended Attributes data
sets be within 4 months of each other.
Implementation
This section explains how to implement and use MLD Extended Attributes data in your
application.
1. Set up your data.
• On Windows/UNIX/Linux:
– Install the MLD and streets and their associated license files. Note the paths to
these folders.
– Install the MLD Extended Attributes data set. The MLD Extended Attributes data
set needs to be unzipped and copied to a folder. Note the path to this folder.
– Define the data paths to DVDMLD, DVDMLD2 and the folder where you installed
the MLD Extended Attributes data set, as well as any other geocoding data sets
you have installed for your application. Define the paths to the associated
license files and passwords.
• On z/OS:
– Upload the MLD, streets, and MLD Extended Attributes data sets.
– There are multiple extatt*p.dld files. There needs to be a separate DD in your
JCL for each file. The DD names are EXTATTnn, where nn=01 - total number of
extatt*p.dld files. For example, to retrieve and access APN and elevation data
from the MLD Extended Attributes data set, you would have the following DDs in
your JCL:
//GSDFILE DD DSN=&GEOSPFX..US.GSD,DISP=SHR
//GSDFIL01 DD DSN=&GEOSPFX..MPOINTS1.GSD,DISP=SHR <=== MLD file
//GSIFILE DD DSN=&GEOSPFX..MPOINTS1.GSI,DISP=SHR <=== MLD alias file
//GSDFIL02 DD DSN=&GEOSPFX..MPOINTS2.GSD,DISP=SHR <=== MLD file
//GSIFIL01 DD DSN=&GEOSPFX..MPOINTS2.GSI,DISP=SHR <=== MLD alias file
//GSDFIL03 DD DSN=&GEOSPFX..MPOINTS3.GSD,DISP=SHR <=== MLD file
//GSIFIL02 DD DSN=&GEOSPFX..MPOINTS3.GSI,DISP=SHR <=== MLD alias file
2. For Windows/UNIX/Linux:
The MLD Extended Attributes data is delivered in multiple .dld files, extatt*p.dld,
where "*" is a number. When installed, GeoStan will automatically detect and load these
files, and set the Status File MLD Extended Attributes property.
3. When initializing GeoStan, you can optionally query the Status File MLD Extended
Attributes property to confirm the extatt*p.dld files, loaded successfully.
C GS_STATUS_FILE_MLD_EXTENDED_ATTR
COBOL GS-STATUS-FILE-MLD-EXTEND-ATTR
JAVA STATUS_FILE_MLD_EXTENDED_ATTR
.NET GS_STATUS_FILE_MLD_EXTENDED_ATTR
C sample code:
GsPropGetBool(&statusProps, GS_STATUS_FILE_MLD_EXTENDED_ATTR, &bVal);
if (!bVal) {
printf("MLD Extended Attribute data failed to initialize.\n");
exit(1);
}
C For APN:
Use GsDataGet or GsMultipleGet to return GS_APN_ID.
For elevation:
Use GsDataGet or GsMultipleGet to return
GS_PARCEN_ELEVATION or
GS_PARCEN_ELEVATION_METERS
C sample code:
GsDataGet(gs, GS_OUTPUT, GS_APN_ID, apn,
sizeof(apn));
GsDataGet(gs, GS_OUTPUT, GS_PARCEN_ELEVATION, elevation,
sizeof(elevation));
PreciselyID Fallback
When using PreciselyID Fallback, if an address match is not made to Master Location Data,
but a match is made to a different data set, the PreciselyID unique identifier of the nearest
MLD point located within the search distance is returned. To distinguish when a fallback
PreciselyID unique identifier is returned, the GS_PB_KEY return value contains a leading
character of "X" rather than "P", for example: X00001XSF1IF. Note, all of the other fields
returned for the address match, including the geocode and all associated data returns from
GeoStan, reflect the match results for the input address. The fallback PreciselyID unique
identifier can then be used for the lookup to the GeoEnrichment data set(s), and the
attribute data for the fallback location is returned for the match.
The relevance and accuracy of the returned attribute data using a PreciselyID Fallback
location is highly dependent on the type of GeoEnrichment data, as well as the PreciselyID
Fallback search distance. PreciselyID Fallback is intended for use with GeoEnrichment data
sets that have polygonal-based data, rather than point-specific data. For example, the
PreciselyID Fallback option may be suitable for determining the FEMA flood zone for a
given location using the Flood Risk Pro GeoEnrichment data set since it contains data that
represents a polygonal region rather than a single coordinate. However, it is important to
note that the accuracy of the returned data would very much depend on the size and nature
of the individual polygonal features described in the GeoEnrichment data, combined with
the search distance used to locate the nearest Master Location Data point. The search
distance is configurable with an allowable search radius of 0-5280 feet and a default value
of 150 feet.
Requirement
PreciselyID Fallback requires that you have licensed and installed Master Location Data.
Note: PreciselyID Fallback can only be used in forward and reverse geocoding.
PreciselyID Fallback is disabled by default; the following steps describe how to enable this
feature:
1. Enable the Init Options Spatial Query initialization property.
2. Enable the Approximate PBKey find property.
3. Optional. Set the search distance. Valid values = 0-5280 feet. Default = 150 feet.
The following table defines the related initialization and find properties for each API.
C 1. Enable GS_INIT_OPTIONS_SPATIAL_QUERY.
2. Enable GS_FIND_APPROXIMATE_PBKEY.
3. Optionally, set GS_FIND_SEARCH_DIST.
The PreciselyID unique identifier field is a 12-character, alpha-numeric string with 1 null
terminator, that has ‘P’ as the leading character. For the fallback PreciselyID unique
identifier, the leading character is an ‘X’, for example: X00001XSF1IF.
The following table describes how to return the PreciselyID unique identifier when one is
available.
Note: Fallback PreciselyID unique identifiers are not returned when using GsHandleGet.
C Use either GsDataGet, GsHandleGet or GsMultipleGet to
return GS_PB_KEY.
Licensing
Reverse PreciselyID Lookup requires a special license. There are two levels of licensing for
Reverse PreciselyID Lookup:
• Standard - This license allows Reverse PreciselyID Lookup of all of the standard
MLD addresses.
• Enhanced - This license allows Reverse PreciselyID Lookup of a portion of MLD
addresses that require an additional royalty due to address sourcing constraints.
Requirements
Implementation
This section explains how to implement the Reverse PreciselyID Lookup feature in your
application.
1. Set up your data.
• On Windows/UNIX/Linux:
– Install the MLD, streets and MLDR data sets and their associated license files.
Note the paths to these folders.
– Define the data paths to DVDMLD, DVDMLD2 and DVDMLDR, as well as any
other geocoding data sets you have installed for your application. Define the
paths to the associated license files and passwords.
• On z/OS:
– Upload the MLD, streets and MLDR data sets.
– There is one Reverse PreciselyID file (.pbk) for each state/territory. There needs
to be a separate DD in your JCL for each file. The DD names are <st>MLDPBK,
where <st> is each state abbreviation. For example, to perform Reverse
PreciselyID Lookups, you would have the following DDs in your JCL continuing
with the individual Reverse PreciselyID state files until all are listed:
2. To confirm the Reverse PreciselyID Lookup files (*.pbk) loaded successfully, you can
query the Status File Reverse PreciselyID status output property that is appropriate for
your API:
C GS_STATUS_FILE_REVERSE_PBKEY
COBOL GS-STATUS-FILE-REVERSE-PBKEY
JAVA STATUS_FILE_REVERSE_PBKEY
.NET GS_STATUS_FILE_REVERSE_PBKEY
3. Include the input PreciselyID field by calling the Set Data function using the input
PreciselyID field name that is appropriate for your API:
C GS_PB_KEY
COBOL GS-PB-KEY
JAVA PB_KEY
.NET GS_PB_KEY
When using Reverse PreciselyID Lookup, the search results can return zero to many MLD
point address variations that match the input PreciselyID. There will be no matches
returned if the given PreciselyID is not found. While many PreciselyIDs map to a single
point-level address, some PreciselyIDs map to multiple point address variations. Getting
multiple point address variations from one PreciselyID can occur in two circumstances:
The following table lists the Return Codes and Match Codes returned with Reverse
PreciselyID Lookup.
Note: When there are one or more address variations for a Reverse PreciselyID Lookup,
the match code returned by GsMultipleGet() is always “V000”.
The USPS Locatable Address Conversion System (LACS) corrects addresses that have
changed as a result of a rural route address converting to street-style address, a PO Box
renumbering, or a street-style address changing. The following are examples of LACSLink
conversions:
• Rural Route Converted to Street-Style Address:
Old Address:
RR 3 Box 45
New Address:
1292 North Ridgeland Dr
• Street Renamed and Renumbered:
Old Address:
23 Main St
New Address:
45 West First Ave
• PO Box Renumbered:
Old Address:
PO Box 453
New Address:
PO Box 10435
If you have licensed the LACSLink processing option, you must install the LACSLink data and
set the LACSLink initialization properties for GeoStan to process your address through
LACSLink. For more information on LACSLink, see Appendix F: USPS Link products.
Understanding SuiteLink
The purpose of SuiteLink™ is to improve business addressing by adding known secondary
(suite) numbers to allow delivery sequencing where it would otherwise not be possible.
SuiteLink uses the input business name, street number location, and 9 digit ZIP+4 to return
a unit type (i.e. "STE") and unit number for that business.
As an example, when entering the following address with SuiteLink enabled in CASS mode.
UT Animal Research
910 Madison Ave
Memphis TN 38103
If you have licensed the SuiteLink processing option, you must install the SuiteLink data and set
the SuiteLink initialization properties for GeoStan to process your address through SuiteLink.
For more information on SuiteLink, see Appendix F: USPS Link products overview.
For more information on SuiteLink enums and functions, see the following sections:
• “Enums for storing and retrieving data” on page 96 for C and page 279 for COBOL.
• GsFindWithProps properties
Note: The USPS provides an unspecified amount of time for people to convert their
addresses to the new location via ZIPMove, and then the record is removed from
ZIPMove data, assuming people have corrected their address databases. If
GS_IS_ALIAS returns “A13”, be sure to update your address database.
GS_LOT_CODE Single character string (2 including the NULL) indicating the direction
of carrier travel.
• A – Ascending
• D – Descending
Option Description
Offset Distance Sets the offset distance from the street segment.
Squeeze Distance Set the distance to offset the first and last address-level geocodes from the street ends.
Search Distance Sets the radius in which GeoStan searches for a match to the input geocode.
Searchable Address Sets the type of match candidates that you allow GeoStan to match against. This can
Types include intersections, addresses interpolated on street segments, street segments with
no number range, and point data locations.
Reverse geocoding to Sets matching to the nearest point address that is within the specified Search Distance,
points matching rather than to the closest feature (e.g. street segment or intersection as well as point
addresses).
In this chapter
This chapter lists the public functions of the C API in alphabetical
order. The following sections provide a quick reference to the data
types and functions; organized by usage.
C API data types and functions 87
Data types 95
Enums for storing and retrieving data 96
GsFindWithProps properties 122
GsInitWithProps properties 146
C Functions 163
C API data types and functions
Data types and enum functions
Data types
Provides information on the data types used by the C functions.
GsFindWithProps properties
Lists the GsFindWithProps find properties.
GsInitWithProps properties
Lists the GsInitWithProps initialization properties.
GsFileStatus
Returns if the files successfully opened, and the date of the USPS data used in generating
the primary GSD file.
GsFileStatusEx
Returns information about the current GeoStan data set and license.
GsGetLibVersion
Returns the current version of the GeoStan library.
GsInitWithProps
Initializes GeoStan using properties.
GsTerm
Terminates GeoStan.
GsCityDataGet
Retrieves data for the found city record.
GsCityFindFirst
Finds the first city matching the partial name or valid ZIP Code.
GsCityFindNext
Finds the next matching city.
GsFindFirstState
Finds the first state matching the name, abbreviation, or valid ZIP Code.
Address lookup
GsDataGet
Returns data for all address and matched elements from GeoStan.
GsDataSet
Passes data for all address elements to GeoStan.
GsFindWithProps
Finds a match with user settable match preferences (properties).
GsGetCoordsEx
Retrieves coordinates for the street segment found via GsFindWithProps.
GsMultipleGet
Returns the address elements for the match candidate specified
GsMultipleGetHandle
Returns the range handle for the match candidate specified.
GsNumMultiple
Returns the number of match candidates found.
GsSetSelection
Allows you to select a match from a set of match candidates.
GsHandleGet
Retrieves data for objects found via GsFindFirst and GsFindNext.
GsHandleGetCoordsEx
Retrieves the coordinates for a street segment object found via GsFindFirst and
GsFindNext.
GsGetDBMetadata
Populates the supplied buffer with the information about the item being queried for the
specified database.
GsGetNumDB
Returns the number of loaded databases.
GsErrorGet
Retrieves current error information.
GsErrorGetEx
Retrieves informational messages, error messages, and fatal warnings for the current
GeoStan thread.
GsErrorHas
Indicates if any errors occurred or any informational messages are available in the current
thread.
GsFindFirst___
Finds the first street, segment, or range object that meets the search criteria.
GsFindNext___
Finds the next street, segment, or range object that meets the search criteria.
GsSetSelectionRange
Allows GeoStan to use a record found outside of GsFindWithProps as a match.
GsFindGeographicFirstEx
Finds the first geographic centroid match for a city, county, and or state from the set of
possible matches found.
GsFindGeographicNext
Finds the next geographic centroid match for a city, county, and or state from the set of
possible matches found.
GsFindGeographicNextEx
Finds the next geographic centroid match for a city, county, and or state from the set of
possible matches found.
Utilities
GsClear
Clears the data buffer in the internal data structures.
GsSoundex
Generates a soundex key for use in GsFindFirst.
GsTestRange
Tests if a house number falls within a range.
GsVerifyAuxiliaryRecord
Validates an auxiliary file record.
GsVerifyGSDDataPresent
Validates the presence of data for specified states in the GSD data file.
GsZ4Changed
Determines if the USPS changed a ZIP + 4 address definition since GeoStan last
processed the record.
GsFormatCASSHeader
Writes a CASS 3553 report to the header buffer argument.
GsWriteExtendCASSReport
Writes a USPS CASS report based on the specified template.
GsDpvGetCompleteStats
Obtains the complete DPV statistics since the application initialized DPV.
GsDpvGetFalsePosDetail
Retrieves the detail record for a DPV false-positive report.
GsDpvGetFalsePosHeaderStats
Retrieves DPV statistics for the header record for a DPV false-positive report.
GsFormatDpvFalsePosDetail
Formats a DPV false-positive detail record from GsDpvGetFalsePosHeaderStats.
GsFormatDpvFalsePosHeader
Formats a DPV false-positive header record with data from GsDpvGetFalsePosDetail.
GsFormatLACSFalsePosDetail
GsFormatLACSFalsePosHeader
GsLACSClearStats
GsLACSGetCompleteStats
Obtains the complete LACSLink statistics since the application initialized LACSLink.
GsLACSGetFalsePosHeaderStats
Retrieves LACSLink statistics for the header record for a LACSLink false-positive report.
GsFindFirstSegmentByMbr
Finds the first segment handle within the specified MBR.
GsFindNextSegmentByMbr
Finds the first segment handle within the specified MBR.
GsGetMbr
Returns an MBR for the specified geographic element.
GsPrepareIndexFinance
Prepares all .gsx files needed to cover the finance area.
GsPrepareIndexMbr
Prepares all .gsx files needed to cover the minimum bounding rectangle (MBR).
GsPropSetBool
Sets a boolean property.
GsPropSetDouble
Sets a double property.
GsPropSetLong
Sets an integer property.
GsPropSetPtr
Sets a pointer property.
GsPropGetBool
Retrieves a boolean property.
GsPropGetDouble
Retrieves a double property.
GsPropGetInfo
Retrieves information about a property.
GsPropGetLong
Retrieves an integer property.
GsPropGetPtr
Retrieves a pointer property.
GsPropGetStr
Retrieves a string property.
GsPropGetStrLen
Retrieves the length of the string value of a property.
GsPropListCreate
Creates and initializes a property list for GeoStan initialization.
GsPropListClear
Clears (empties) a property list.
GsPropListDestroy
Destroys a property list.
GsPropFind
Finds a property in a property list.
GsPropGetNext
Iterates to the next sequential property in the property list.
GsPropListGetCount
Retrieves the number of properties in a property list.
GsPropListGetType
Retrieves the type of the property list.
GsPropListRead
Reads the property list from a file or character string.
GsPropListReset
Resets the property list to its default state.
GsPropRemove
Removes a property from the property list.
GsPropListWrite
Writes the property list to a file or character string.
GsHandleGet • Street
A bullet indicates this enum is valid when using a Street handle with
GsHandleGet. Includes only Street level information.
• Segment
A bullet indicates this is valid when using a Segment handle with
GsHandleGet. Includes Street and Segment information.
• Range
A bullet indicates this enum is valid when using a Range handle with
GsHandleGet. Includes Street, Segment, and Range information.
GsDataGet • Input
A bullet indicates this is valid when using input flag with this function.
• Output
Indicates this enum is valid when using the output flag with this function.
Can be:
– A – Valid for non-intersection matches only
– I – Valid for intersection matches only
– L - Valid for street locator matches only
– P - Points data match.
– R - Reverse geocoding only.
– Bullet – Valid for all types of match
Length A number indicating the largest string GeoStan returns for this enum. This
length includes a NULL-termination character. Symbolic constants use the
naming convention <<NAME>>_LENGTH. For example the enum
GS_ADDRLINE returns the input or output address line. The maximum
length of an address line is 61. Therefore, the symbolic constant is
GS_ADDRLINE_LENGTH and is defined as 61.
Description A brief explanation of the information returned. If you use an invalid enum,
GeoStan returns an Invalid Argument error.
GS_ADDRLINE 256
First address line or address line for single line addresses.
For single line addresses, enter address line and last line
combined as a single input, for example,
“4750 Walnut St 80301”.
GS_ADDRLINE_SHORT 61
Shortest possible address line that can be constructed from
available short street name and the other address line
components.
GS_ADDR2 61
Second address line.
GS_ALIAS
Use this to specify alias info instead of normal.
GS_ALT_FLAG 2 A
Base/Alternate record
• B – Base
• A – Alternate
GS_AUX_USERDATA 301
User data from the auxiliary file. Blank if no auxiliary file.
GS_BEARING 6
Compass direction, in decimal degrees, from the point data
match to the centerline match. Measured clockwise from 0
degrees north.
GS_BLOCK 16 A A
15-digit census block ID/census FIPS code, using the
syntax sscccttttttgbbb where:
• ss – 2-digit State FIPS Code
• ccc – 3-digit County FIPS Code
• tttttt – 6-digit Census Tract FIPS Code
• g – Single-digit Block Group FIPS Code, and
• bbb – Block FIPS Code
If the address is on the left side of the street, GS_BLOCK will
contain the equivalent of GS_BLOCK_LEFT. If the address
is on the right, GS_BLOCK will contain the equivalent of
GS_BLOCK_RIGHT.
GS_BLOCK_LEFT 16
Census block ID from the left side of the street.
GS_BLOCK_LEFT2 16 I I
GS_BLOCK_LEFT for the second segment in the
intersection.
GS_BLOCK_RIGHT 16
Census block ID from the right side of the street.
GS_BLOCK_RIGHT2 16 I I
GS_BLOCK_RIGHT for the second segment in the
intersection.
GS_BLOCK_SFX 2 A
Current block suffix for Census 2010 geography.
GS_BLOCK_SFX_LEFT 2
Current left block suffix for Census 2010 geography.
GS_BLOCK_SFX_LEFT2 2 I I
GS_BLOCK_SFX_LEFT for the second segment in the
intersection.
GS_BLOCK_SFX_RIGHT 2
Current right block suffix for Census 2010 geography. Blank
if the matched record is from point-level data.
GS_BLOCK_SFX_RIGHT2 2 I I
GS_BLOCK_SFX_RIGHT for the second segment in the
intersection.
GS_CART 5 A A
Carrier route.
GS_CBSA_DIVISION_NAME 128
The name of the Core Based Statistical Area (CBSA)
division in which the address is located. A CBSA division is
a metropolitan statistical area with a population of at least
2.5 million that has been subdivided to form smaller
groupings of counties referred to as "metropolitan divisions".
GS_CBSA_DIVISION_NAME2 128 I
GS_CBSA_DIVISION_NAME for the second segment in the
intersection.
GS_CBSA_DIVISION_NUMBER 6
The code number of the Core Based Statistical Area (CBSA)
division in which the address is located.
GS_CBSA_DIVISION_NUMBER2 6 I
GS_CBSA_DIVISION_NUMBER for the second segment in
the intersection.
GS_CBSA_NAME 128
The name of the Core Based Statistical Area in which the
address is located. A CBSA is a U.S. geographic area
defined by the Office of Management and Budget (OMB)
based around an urban center of at least 10,000 people and
adjacent areas that are socioeconomically tied to the urban
center by commuting.
GS_CBSA_NAME2 128 I
GS_CBSA_NAME for the second segment in the intersection.
GS_CBSA_NUMBER 6
The code number of the Core Based Statistical Area (CBSA)
in which the address is located.
GS_CBSA_NUMBER2 6 I
GS_CBSA_NUMBER for the second segment in the
intersection.
GS_CHECKDIGITb 2 A
Check digit.
GS_CITY 29
Abbreviated city name from the last line of the input or
output address; the value from GS_NAME_CITY or
GS_PREF_CITY.
GS_CITY_SHORT 29
The output city name that appears in
GS_LASTLINE_SHORT. This value is determined by logic
similar to GS_CITY. Whenever possible, this city name is
13 characters or less.
This output city name is determined by CASS rules. This
can be either City State Name, City State Name
Abbreviation, or Preferred Last Line City State Name.
GS_CLOSE_MATCH
Indicates if the address was a Close match.
• T - Match candidate is a Close match to the input
address.
• F - Match candidate is not a Close match to the input
address.
GS_COUNTY 6
County FIPS code. (For GsHandleGet and
GsMultipleGet this is the USPS county for the Range
record. For GsDataGet this is the county from the segment
record or the USPS county if matched to a USPS only
range.)
GS_COUNTY2 6 I
GS_COUNTY for the second segment in the intersection.
GS_COUNTY_FIPS 4
County FIPS code
GS_COUNTY_NAME 128
County name.
GS_COUNTY_NAME2 128 I
GS_COUNTY_NAME for the second segment in the
intersection.
GS_CSA_NAME 128
The name of the Combined Statistical Area (CSA) in which
the address is located. A CSA consists of two or more
adjacent CBSAs that have substantial employment
interchange.
GS_CSA_NAME2 128 I
GS_CSA_NAME for the second segment in the intersection.
GS_CSA_NUMBER 4
The code number for the CSA in which the address is
located.
GS_CSA_NUMBER2 4 I
GS_CSA_NUMBER for the second segment in the
intersection.
GS_CTYST_KEY 7
USPS city state key (an alphanumeric value that uniquely
identifies a locale in the USPS city state product).
GS_DATATYPE 3
Type of data used to make the match.
• 0 – USPS data
• 1 – TIGER data
• 2 – TomTom street-level data
• 3 – Sanborn point-level data
• 4 – Deprecated
• 5 – Deprecated
• 6 – HERE (formerly NAVTEQ) street-level data
• 7 – TomTom point-level data
• 8 – Centrus point-level data
• 9 – Auxiliary file data
• 10 – User Dictionary
• 11 – HERE (formerly NAVTEQ) point-level data
• 12 – Master Location Data
GS_DATATYPE2 3 I
GS_DATATYPE for the second segment in the
intersection.
GS_DFLTb 2 A
Indicates the return status of GS_HI_RISE_DFLT and
GS_R_RTE_DFLT
• Y – Either GS_HI_RISE_DFLT or GS_R_RTE_DFLT
returned Y.
• Blank – Both GS_HI_RISE_DFLT and
GS_R_RTE_DFLT returned N or Blank.
GS_DPBCb 3 A
Delivery Point Bar Code.
GS_DPV_CONFIRM 2 A
Indicates if a match occurred for DPV data.
• N – Nothing confirmed
• Y – Everything confirmed (ZIP + 4, primary, and
secondary)
• S – ZIP + 4 and primary (house number) confirmed
• D – ZIP + 4 and primary (house number) confirmed and
a default match (GS_HI_RISE_DFLT = Y), secondary
did not confirm.
• Blank – non-matched input address to USPS ZIP + 4
data, or DPV data not loaded
GS_DPV_CMRA 2 A
DPV CMRA indicator.
• Y – Address found in CMRA table
• N – Address not found in CMRA table
• Blank – DPV not loaded
GS_DPV_FALSE_POS 2 A
DPV false-positive indicator.
• Y – False-positive match found
• Blank – False-positive match not found
GS_DPV_FOOTNOTE1 3 A
Information about matched DPV records.
• AA – ZIP + 4 matched
• A1 – Failure to match a ZIP + 4
• Blank – Address not presented to hash table or DPV data
not loaded
GS_DPV_FOOTNOTE2 3 A
Information about matched DPV records.
• BB – All DPV categories matched
• CC – DPV matched primary/house number, where the
secondary/unit number did not match (present but
invalid)
• M1 – Missing primary/house number
• M3 – Invalid primary/house number
• N1 – DPV matched primary/house number, with a
missing secondary number
• P1 – Missing PS, RR, or HC Box number
• P3 – Invalid PS, RR or HC Box number
• F1 – All military addresses
• G1 – All general delivery addresses
• U1 – All unique ZIP Code addresses
• Blank – Address not presented to hash table or DPV data
not loaded
GS_DPV_FOOTNOTE3 3 A
Information about matched DPV records.
• R1 – Matched to CMRA but PMB designator not present.
• RR – Matched to CMRA and PMB designator present
(PMB 123 or # 123).
• Blank – Address not presented to hash table or DPV data
not loaded
GS_DPV_FOOTNOTE4 3 A
Reserved by USPS for future use.
GS_DPV_FOOTNOTE5 3 A
Reserved by USPS for future use.
GS_DPV_FOOTNOTE6 3 A
Reserved by USPS for future use.
GS_DPV_NO_STAT 2 A
• Y - The address is valid for CDS pre-processing.
• N - The address is not valid for CDS pre-processing.
• Blank - DPV is not loaded or DPV did not confirm.
GS_DPV_SHUTDOWN 2 A
• Y - Address was found in false-positive table.
• N - Address was not found in false-positive table.
• Blank - Address was not presented to hash table or DPV
data not loaded.
GS_DPV_VACANT 3 A
• Y - The address is vacant.
• N - The address is not vacant.
• Blank - DPV is not loaded or DPV did not confirm (so
vacancy is irrelevant).
GS_EWS_MATCH 2 A
Indicates if GeoStan made an EWS match.
• Y – Match denied because it matched to EWS data.
• Blank – Input record did not match to EWS data.
GS_FIRM_NAME 41 A A
Name of firm from the USPS data or the input firm name.
GS_GOVT_FLAG 2 A A
Government building indicator.
• A – City government building
• B – Federal government building
• C – State government building
• D – Firm-only
• E – City government building and firm only
• F – Federal government building and firm only
• G – State government building and firm only
A, B, C, E, F, and G are valid for alternate records only
(GS_ALT_FLAG=A). D is valid for both base and alternate
records.
GS_HI_RISE_DFLT 2 A A
Indicates if GeoStan matched to a highrise.
• N – Matched to an exact highrise record or a street record
• Y – Did not match to an exact record. Matched to the
USPS default highrise record or a street record. Check
the input address for accuracy and completeness.
• Blank – Does not apply to the input address (for example,
PO Boxes and General Delivery addresses) or did not
find a match.
GS_HIRANGE 12 A A
House number at high end of range.
GS_HIUNIT 12 A A
High unit number.
GS_HIZIP4 5 A
High ZIP + 4 for this range.
GS_HOUSE_NUMBER 12 A
House number of input or output address.
GS_HOUSE_NUMBER2 12 A
Second house number for a ranged house number match. If
GS_FIND_ADDRESS_RANGE is enabled, the second
number in the ranged address.
GS_INC_IND 2 A, P A, P
Incorporated Place Indicator.
• I – Incorporated place
• N – Not an incorporated place
• X – Unknown
GS_INTERSECTION 2
Indicates if the address is an intersection.
• T – Input address is an intersection
• F – Input address is a street address
GS_IS_ALIAS 4 A
The first character is:
• N – Normal street match
• A – Alias match (including buildings, aliases, firms, etc.)
The next 2 characters are:
• 01 – Basic index, normal address match
• 02 – USPS street name alias index
• 03 – USPS building index
• 05 – Statewide intersection alias (when using the
Usw.gsi, Use.gsi,or US.gsi file).
• 06 – Spatial data street name alias (when using the
Us_pw.gsi, Usw.gsi, Us_pe.gsi, Use.gsi,
Us_ps.gsi, Usp.gsi, Us_psw.gsi, or
Us_pse.gsi file is required.)
• 07 – Alternate index (when using Zip9.gsu,
Zip9e.gsu, and Zip9w.gsu)
• 08 – LACSLink
• 09 – Auxiliary file match.
• 10 – Centrus Alias index (when using usca.gsi)
• 11 – POI index (when using poi.gsi)
• 12 – USPS Preferred Alias
• 13 – ZIPMove match (when using us.gsz)
• 14 – Expanded Centroids match (when using
us_cent.gsc)
• 15 – PPOI index (when using ppoi1.gsi, 2.gsi,
3.gsi)
GS_LACS_FLAG 2 A A
Indicates if GeoStan marked the address for conversion.
• L – Address marked for LACS conversion.
• Blank – Address not marked for LACS conversion.
GS_LACSLINK_IND 2 A
LACSLink indicator.
• Y – Matched LACSLink record
• N – LACSLink match NOT found
• F – False-positive LACSLink record
• S – Secondary information (unit number) removed to
make a LACSLink match
• Blank – Not processed through LACSLink
GS_LACSLINK_SHUTDOWN 2 A
• Y – False-positive occurred and LACSLink library
shutdown.
• N – LACSLink library has not shutdown or not loaded.
GS_LACSLINK_RETCODE 3 A
LACSLink return code.
• A – Matched LACSLink record
• 00 – LACSLink match NOT found
• 09 – Matched to highrise default, but no LACSLink
conversion
• 14 – Found LACSLink match, but no LACSLink conversion
• 92 – Secondary information (unit number) removed to
make a LACSLink match
• Blank – Not processed through LACSLink
GS_LASTLINEc 61
Complete last line (ZIP + 4 not available with
GsMultipleGet or intersection matches).
GS_LASTLINE_SHORT 61
This is the address "lastline". It contains the values of
GS_CITY_SHORT, GS_STATE, and GS_ZIP10.
Whenever possible, this field is 29 characters or less:
• 13-character city name
• 2 (comma and space)
• 2-character state abbreviation
• 2 spaces
• 10-digit ZIP code
GS_LAT 11
Latitude of located point (in millionths of degrees).
GS_LINE1 104
GS_LINE2
GS_LINE3
GS_LINE4
GS_LINE5
GS_LINE6
Used for multiple line entry. GeoStan does not process
these as output.
PMB_DESIGNATOR and PMB_NUMBER are not returned in
this mode.
GS_LOC_CODE 5
Location code. For descriptions of location codes, see the
Status Codes appendix.
GS_LON 12
Longitude of located point (in millionths of degrees).
GS_LORANGE 12 A A
House number at low end of range.
GS_LOT_CODEb 2 A
• A – Ascending
• D – Descending.
eLot ascending and descending value. Only available for
addresses GeoStan can standardize.
GS_LOT_NUMb 5 A
4-digit eLOT number. Requires an input address GeoStan
can standardize.
GS_LOUNIT 12 A A
Low unit number.
GS_LOZIP4 5 A
Low ZIP + 4 for this range.
GS_MAIL_STOP 61
Returns address information appearing after mail stop
designator words: MSC, MS, MAILSTOP, MAIL STOP,
ATTN, ATTENTION.
GS_MATCH_CODE 5
Match code. For descriptions of match codes, see the
Status Codes appendix.
GS_MATCHED_DB
Index of database for matched record.
GS_MCD_NAME 41
Minor Civil Division name from the auxiliary file. Blank if no
auxiliary file match.
GS_MCD_NUMBER 6
Minor Civil Division number from the auxiliary file. Blank if no
auxiliary file match.
GS_METRO_FLAG 2
Indicates if GS_CBSA_NAME
• Y – Contains “Metropolitan Statistical Area”
• N – Is non-blank but does not contain “Metropolitan
Statistical Area”
• Blank – Is blank (the county does not contain a CBSA).
GS_METRO_FLAG2 2 I
GS_METRO_FLAG for the second segment in the
intersection.
GS_MM_RESULT_CODE 12
Returns a MapMarker style result code.
GS_NAME 41
Street name
GS_NAME2 41 I I I
Second street name in an intersection match.
GS_NAME_CITY 29
City name for the matched address from the City State
record.
GS_NAME_SHORT 41
The short street name field contains the short street name
used to construct the short address line.
All attempts are made to abbreviate this name according to
the process specified by the USPS in the 30 Character
Abbreviation - Cycle M Flow Chart. If an abbreviated
address cannot be constructed that is 30 characters or less,
this field then contains the same street name value as the
GS_NAME field enum return.
GS_PERCENT_GEOCODE 5 R A
Percentage along the street segment to the interpolated
match. The range is 0.0 - 100.0. The range is always 0.0 for
point data.
GS_PMB_DESIGNATOR 5 A
PMB designator (always “PMB”).
GS_PMB_NUMBER 9 A
PMB number.
GS_POSTDIR 3
Postfix direction. Can be blank, N, S, E, W, NE, NW, SW, or
SE.
GS_POSTDIR2 3 I I I
Cross street postfix direction.
GS_POSTDIR_SHORT 3
Postdir from the GS_ADDRLINE_SHORT.
GS_PREDIR 3
Prefix direction. Can be blank, N, S, E, W, NE, NW, SW, or
SE.
GS_PREDIR2 3 I I I
Cross street prefix direction.
GS_PREDIR_SHORT 3
Predir from the GS_ADDRLINE_SHORT.
GS_PREF_CITY 29
Preferred city name for the output ZIP Code of the matched
address.
GS_QCITY 10
State , city , or finance numbers.
GS_R_RTE_DFLT 2 A A
Match indication for rural routes.
• N – Matched to an exact rural route record.
• Y – Did not find an exact record. Matched to the USPS
default rural route record. Check the input address for
accuracy and completeness.
• Blank – Does not apply to the input address (for example,
street addresses, P.O. Boxes, and General Delivery
addresses) or no match found.
GS_RANGE_PARITY 41 A
Indicates the parity of the house number in the range.
• E – Even
• O – Odd
• B – Both
GS_RDI_RETCODE 2 A
USPS Residential Delivery Indicator (requires DPV-
confirmed ZIP+4)
• Y - Address is a residence
• N - Address is a business
• Blank - Address was not presented to RDI or RDI data
not loaded
GS_REC_TYPEb 2 A A
Range record type.
• A – Auxiliary file
• F – Firm
• G – General delivery
• H – Highrise
• P – PO Box
• R – Rural route/highway contract
• S – Street
• T – TIGER file
• U - User Dictionary
GS_RESOLVED_LINE 5
indicates which line in a 2-line address GeoStan used to
resolve the address. Relates to GS_ADDRLINE and
GS_ADDR2 with GsDataSet.
GS_ROAD_CLASS 3 A
Road class code.
• 0 – Minor road, main data file
• 1 – Major road, main data file
• 10 – Minor road, supplemental file
• 11 – Major road, supplemental data file
GS_ROAD_CLASS2 3 I
GS_ROAD_CLASS for the second segment in the
intersection.
GS_SEG_HIRANGE 12
High house number in segment.
GS_SEG_HIRANGE2 12 I
GS_SEG_HIRANGE for the second segment in the
intersection.
GS_SEG_LORANGE 12
Low house number in segment.
GS_SEG_LORANGE2 12 I
GS_SEG_LORANGE for the second segment in the
intersection.
GS_SEGMENT_DIRECTION 2
• F – Numbers are forward
• R – Numbers are reversed
GS_SEGMENT_DIRECTION2 2 I
GS_SEGMENT_DIRECTION for the second segment in the
intersection.
GS_SEGMENT_ID 11
Segment ID (TLID) or unique ID from premium data
vendors.
GS_SEGMENT_ID2 11 I
GS_SEGMENT_ID for the second segment in the intersection.
GS_SEGMENT_PARITY 2
Odd numbers in the segment are on:
• L – Left side of the street
• R – Right side of the street
• B – Both sides of the street
• U – Unknown
GS_SEGMENT_PARITY2 2 I
GS_SEGMENT_PARITY for the second segment in the
intersection.
GS_STATE 3
State abbreviation.
GS_STATE_FIPS 3
State FIPS code.
GS_STREET_SIDE 2 A
The matched address is on the following side of the street:
• L – Left side of the street
• R – Right side of the street
• B – Both sides of the street
• U – Unknown side of the street
This is relative to the segment end points and the segment
direction (GS_SEGMENT_DIRECTION).
NOTE: This enum does not reflect the value in the "Side
of Street" field of any particular data vendor.
GS_SUITELINK_RET_CODE 4 A
• A - SuiteLink record match.
• 00 - No SuiteLink match.
• Blank - This address was not processed through
SuiteLink.
GS_TYPE 5 l l l l l l l
Street type (also called street suffix).
GS_TYPE2 5 I I I
Cross street type.
GS_TYPE_SHORT 6 l
Postdir from the GS_ADDRLINE_SHORT.
GS_UNIT_NUMBER 12 A A A
Unit number.
GS_UNIT_NUMBER2 12 A A
Second unit number parsed from the address line. Available
in CASS and relaxed modes only.
GS_UNIT_PARITY 2 A
Indicates the parity of the unit number range (GS_LOUNIT
and GS_HIUNIT).
• E – Even
• O – Odd
• B – Both
GS_UNIT_TYPE 5 A A A
Unit type (APT, STE, etc.).
GS_UNIT_TYPE2 5 A A
Second unit type parsed from the address line. Available in
CASS and relaxed modes only.
GS_URB_NAME 31 A
Urbanization name for Puerto Rico.
GS_ZIP 6 A
5-digit ZIP Code.
GS_ZIP4b 5 A A A
4-digit ZIP Code extension.
GS_ZIP9c 10 A A A
9-digit ZIP Code (ZIP + 4).
GS_ZIP10c 11 A A A
9-digit ZIP Code (ZIP + 4) with dash separator.
GS_ZIP_CARRTSORT 2
Indicates the type of cart sort allowed.
• A – Automation cart allowed, optional cart merging
allowed.
• B – Automation cart allowed, optional cart merging not
allowed.
• C – Automation cart not allowed, optional cart merging
allowed.
• D – Automation cart not allowed, optional cart merging
not allowed.
GS_ZIP_CITYDELV 2
Indicates if city-delivery is available.
• Y – Post office has city-delivery carrier routes
• N – Post office does not have city-delivery
GS_ZIP_CLASS 2
ZIP Classification Code:
• Blank – Standard ZIP Code
• M – Military ZIP Code
• P – ZIP Code has P.O. Boxes only
• U – Unique ZIP Code. (A unique ZIP Code is a ZIP Code
assigned to a company, agency, or entity with sufficient
mail volume to receive its own ZIP Code.)
GS_ZIP_FACILITY 2
Returns USPS City State Name Facility Code.
• A – Airport Mail Facility (AMF)
• B – Branch
• C – Community Post Office (CPO)
• D – Area Distribution Center (ADC)
• E – Sectional Center Facility (SCF)
• F – Delivery Distribution Center (DDC)
• G – General Mail Facility (GMF)
• K – Bulk Mail Center (BMC)
• M – Money Order Unit
• N – Non-Postal Community Name, Former Postal
Facility, or Place Name
• P – Post Office
• S – Station
• U – Urbanization
GS_ZIP_UNIQUE 2
• Y – unique ZIP Code. (ZIP Code assigned to a company,
agency, or entity with sufficient mail volume to receive its
own ZIP Code.)
• Blank – Not applicable.
Category Description
Any None.
AnyForward GeoStanReverse
GeoStanAPN
GeoStanFindFirstStreet
GeoStanReverse GeoStanAPN
GeoStanFindFirstStreet
Custom
AnyForward
GeoStanAPN GeoStanFindFirstStreet
Custom
AnyForward
GeoStanReverse
GeoStanFindFirstStreet Custom
AnyForward
GeoStanReverse
GeoStanAPN
Custom GeoStanReverse
GeoStanAPN
GeoStanFindFirstStreet
GeoStan does not allow an application to add a property from the category listed in the
Category column, if the property list already contains a MatchMode property type listed in
the MatchMode value column below:
Custom Relax
Interactive
Close
Exact
GeoStanReverse Custom
GeoStanAPN
GeoStanFindFirstStreet
Relax Custom
Interactive
Close
Exact
Custom
Custom AnyForward
GeoStanReverse
GeoStanAPN
GeoStanFindFirstStreet
CASS BuildingSearch
PreferStreet
PreferPOBox
AddressRange
StreetCentroid
Any MustMatch* property
When the MatchMode is already set to CASS, none of the properties listed in the Property
column can be set. Similarly, if any of the properties in the Property column are already in
the property list, the MatchMode cannot be set to CASS.
This early property conflict detection feature prevents the conflicts described in this section
from occurring.
GS_FIND_ADDRCODE
Type Boolean
Category AnyForward
Usage with other properties in other categories. Compatible with: AnyForward and Any.
Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_WIDE_SEARCH
Type Boolean
Description Considers all records matching the first letter of the street name,
rather than the soundex key on the street name, which allows a
wider search.
This option has no effect when performing a ZIP centroid match.
Category Any
Usage with other properties in other categories. Compatible with: AnyForward, Any, Custom, GeoStanReverse,
GeoStanAPN, and GeoStanFindFirstStreet.
Conflicts with: none.
GS_FIND_SEARCH_AREA
Type Long
Description Assists in finding a match when the input address contains limited
or inaccurate city or ZIP Code information.
Category Any
Usage with other properties in other categories. Compatible with: Any, AnyForward, GeoStanReverse,
GeoStanAPN, and GeoStanFindFirstStreet.
Conflicts with: None.
Default value 0
GS_FIND_BUILDING_SEARCH
Type Boolean
Description Controls the ability to search by building name entered in the address
line. Enables matching to building names even when no unit numbers
are present.
Category AnyForward
Usage with other properties in other Compatible with: AnyForward and Any.
categories. Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
GS_FIND_CENTERLN_PROJ_OF_POINT
Type Boolean
Category AnyForward
Usage with other properties in other Compatible with: AnyForward and Any.
categories. Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_Z9_CODE
Type Boolean
Category AnyForward
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_Z7_CODE
Type Boolean
Description Attempts to find a ZIP+2 centroid match only (no ZIP + 4 or ZIP).
Not valid when using the reverse geocoding options.
Category AnyForward
Usage with other properties in other Compatible with: AnyForward and Any.
categories. Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_Z5_CODE
Type Boolean
Category AnyForward
Usage with other properties in other Compatible with: AnyForward and Any.
categories. Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
GS_FIND_Z_CODE
Type Boolean
Category AnyForward
Usage with other properties in other Compatible with: AnyForward and Any.
categories. Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_PREFER_POBOX
Type Boolean
Description Sets the preference to P.O. Box addresses instead of street addresses for
multi-line input addresses. See “Specifying a preference for street name or
P.O. Box” on page 36 for more information. Ignored if processing in CASS
mode.
If both GS_FIND_PREFER_POBOX and GS_FIND_PREFERSTREET are
set to True, then they are ignored and the default,
GS_FIND_PREFER_STREET is used.
Category AnyForward
Usage with other properties in other Compatible with: AnyForward and Any.
categories. Conflicts with: GeoStanReverse, GeoStanAPN, and GeoStanFindFirstStreet.
Description Sets the preference to street addresses instead of P.O. Box addresses for
multi-line input addresses. Ignored if processing in CASS mode.
If both GS_FIND_PREFER_POBOX and GS_FIND_PREFERSTREET
are set to True, then they are ignored and the default,
GS_FIND_PREFER_STREET is used.
Category AnyForward
Usage with other properties in other Compatible with: AnyForward and Any.
categories. Conflicts with: GeoStanReverse, GeoStanAPN, GeoStanFindFirstStreet
and Custom.
GS_FIND_NEAREST_ADDRESS
Type Boolean
Category GeoStanReverse
Usage with other properties in other Compatible with: Reverse and Any.
categories. Conflicts with: GeoStanAPN, GeoStanFindFirstStreet, Custom,
AnyForward
Usable match modes Reverse geocoding doesn’t use match modes - valid for all match modes.
Category GeoStanReverse
Usage with other properties in other Compatible with: Reverse and Any.
categories. Conflicts with: GeoStanAPN, GeoStanFindFirstStreet, Custom,
AnyForward
Usable match modes Reverse geocoding doesn’t use match modes - valid for all match modes.
GS_FIND_NEAREST_UNRANGED
Type Boolean
Description Specifies that GeoStan can match a street segment with no number ranges.
Enabled with GS_FIND_NEAREST_ADDRESS. Ignored for point data and
intersection matches.
Category GeoStanReverse
Usage with other properties in other Compatible with: Reverse and Any.
categories. Conflicts with: GeoStanAPN, GeoStanFindFirstStreet, Custom,
AnyForward
Usable match modes Reverse geocoding doesn’t use match modes - valid for all match modes.
Description Specifies that GeoStan match an input FIPS and APN code to the Centrus
APN data to receive information on the corresponding parcel.
Category GeoStanAPN
Usage with other properties in other Compatible with: GeoStanAPN and Any.
categories. Conflicts with: GeoStanFindFirstStreet, AnyForward, and
GeoStanReverse.
Description Radius, in feet, that GeoStan searches for a reverse geocode match. The
range is 0 - 5280 feet.
Category GeoStanReverse
Usage with other properties in other Compatible with: GeoStanReverse and Any.
categories. Conflicts with: GeoStanAPN, GeoStanFindFirstStreet, and AnyForward
(see the note above for the exceptions for use in forward geocoding).
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_STREET_OFFSET
Type Long
Description Left and right offset distance from the street segments. The range is 0 - 999
feet.
Category Any
Usage with other properties in other Compatible with: AnyForward, Any, Custom, GeoStanReverse,
categories. GeoStanAPN, and GeoStanFindFirstStreet..
Conflicts with: None.
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
Default value 50
GS_FIND_CENTERLINE_OFFSET
Type Long
Description Offset distance from the street center for a centerline match.
Category AnyForward
Usage with other properties in other Compatible with: AnyForward and Any.
categories. Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
Usable match modes Exact, Close, CASS, Relax, Interactive and Custom.
GS_FIND_CORNER_OFFSET
Type Long
Description Distance, in feet, to offset address-level geocodes from the street end
points. If the corner offset distance is more than half the segment length,
GeoStan sets the distance to the midpoint of the segment.
Category Any
Usage with other properties in other Compatible with: AnyForward, Any, Custom, GeoStanReverse,
categories. GeoStanAPN, and GeoStanFindFirstStreet.
Conflicts with: None.
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
Values
Default value 50
GS_FIND_CLIENT_CRS
Type String
Category Any
Usage with other properties in other Compatible with: AnyForward, Any, Custom, GeoStanReverse,
categories. GeoStanAPN, and GeoStanFindFirstStreet.
Conflicts with: None.
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_MATCH_MODE
Type Long
Category AnyForward
Usage with other properties in other Compatible with: AnyForward and Any.
categories. Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet. In reverse geocoding, this setting is ignored.
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_MIXED_CASE
Type Boolean
Category Any
Usage with other properties in other Compatible with: AnyForward, Any, Custom, GeoStanReverse,
categories. GeoStanAPN, and GeoStanFindFirstStreet.
Conflicts with: none.
Usable match modes Relax, Interactive, Close, Exact, Custom and CASS.
GS_FIND_STREET_CENTROID
Type Boolean
Category AnyForward
GS_FIND_MUST_MATCH_ADDRNUM
Type Boolean
Category Custom
GS_FIND_MUST_MATCH_CITY
Type Boolean
Category Custom
GS_FIND_MUST_MATCH_MAINADDR
Type Boolean
Category Custom
GS_FIND_MUST_MATCH_STATE
Type Boolean
Category Custom
GS_FIND_MUST_MATCH_ZIPCODE
Type Boolean
Category Custom
GS_FIND_CITY_SEARCH
Type Boolean
Category GeoStanFindFirstStreet
Default value
GS_FIND_EXTRA_SEARCH
Type Boolean
Description GeoStan searches the primary street files, Use.gsd and Usw.gsd, and the
supplemental street files, Ustw.gsd and Uste.gsd, for streets without house
numbers.
If you specify this option, pNumber must be blank. If you specify pNumber,
GeoStan searches only the primary street files, Usw.gsd and Use.gsd, which
contain addressed segments. Assign the directory for this file to the pGeoPaths
member of GsInitStruct when calling GsInitWithProps.
NOTE: MVS customers receive one primary street file, Us.gsd, and one
supplemental street file, Ust.gsd.
Category GeoStanFindFirstStreet
Usage with other properties in • Compatible with: GeoStanFind, GeoStanFindFirstStreet, and Any.
other categories.
• Conflicts with:Custom, AnyForward, GeoStanReverse, and GeoStanAPN.
Default value
GS_FIND_SDX_SEARCH
Type Boolean
Category GeoStanFindFirstStreet
Default value
Description GeoStan searches the ZIP Code specified by pLocale. When this option is set with
GsFindFirstStreet, GeoStan performs a finance search.
Category GeoStanFindFirstStreet
Default value
GS_FIND_ADDRESS_RANGE
Type Boolean
Category AnyForward
GS_FIND_ADDRPOINT_INTERP
Type Boolean
Category AnyForward
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_ALTERNATE_LOOKUP
Type Long
Description Determines whether the preferred lookup is to look for the streets first or the firms
first.
Category AnyForward
Default value 3
GS_FIND_APPROXIMATE_PBKEY
Type Boolean
Description When using the Master Location Dataset (MLD), when a match is not made to an
MLD record, this feature returns the GS_PB_KEY of the nearest MLD point
location.
The search radius for the nearest MLD point location can be configured to 0-5280
feet. The default is 150 feet.
This type of match returns a GS_PB_KEY with a leading ‘X’ rather than a ‘P’, for
example, X00001XSF1IF.
The GS_INIT_OPTIONS_SPATIAL_QUERY init property must be set to
True to enable this feature.
For more information, see “PreciselyID Fallback” on page 70.
Usage with other properties in • Compatible with: AnyForward, Any, Custom, GeoStanReverse, GeoStanAPN,
other categories. and GeoStanFindFirstStreet.
• Conflicts with: None.
Description For reverse geocoding, enables matching to the nearest point address within the
search radius, rather than to the closest feature (e.g. street segment or intersection
as well as point addresses).
NOTE: Requires that at least one streets data set and one points data set are
loaded; otherwise, the match will be made to the closest feature.
Category GeoStanReverse
GS_FIND_CORRECT_LASTLINE
Type Boolean
Category AnyForward
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_DB_ORDER
Type String
Usage with other properties in • Compatible with: AnyForward, Any, Custom, GeoStanReverse, GeoStanAPN,
other categories. and GeoStanFindFirstStreet.
• Conflicts with: None.
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
Default value “”
GS_FIND_DPV
Type Boolean
Category AnyForward
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_EXPANDED_SEARCH_RADIUS
Type Long
Category Any
Usage with other properties in • Compatible with: AnyForward, Any, Custom, GeoStanReverse, GeoStanAPN,
other categories. and GeoStanFindFirstStreet.
• Conflicts with: None.
GS_FIND_EXPND_SRCH_LIM_TO_STATE
Type Boolean
Usage with other properties in • Compatible with: AnyForward, Any, Custom, GeoStanReverse, GeoStanAPN,
other categories. and GeoStanFindFirstStreet.
• Conflicts with: None.
GS_FIND_FIRST_LETTER_EXPANDED
Type Boolean
Description Enables extra processing for bad first letter (missing, wrong, etc.).
Category AnyForward
Usable match modes Relax, Interactive, Close, Custom, and CASS. Ignored in Exact mode.
GS_FIND_LACSLINK
Type Boolean
Category AnyForward
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
Description Enables the return of additional address match information. Most notably, this is
used to indicate whether or not an exact match was made to the input unit number.
An address match is still returned if there is not an exact match to the input unit
number, but the match is to the main building address without units. This extended
match code digit will also provide information about any changes in the house
number, unit number and unit type fields. In addition, it can indicate whether there
was address information that was ignored. For more information, see
“Understanding Extended Match Codes” on page 31.
Category AnyForward
Usable match modes Relax, Interactive, Close, Exact, Custom, and CASS.
GS_FIND_POINT_ZIP_MATCH
Type Boolean
Category AnyForward
GS_FIND_PREFER_ZIP_OVER_CITY
Type Boolean
Description Prefer candidates matching input ZIP over matches to input city.
Category AnyForward
Usable match modes Relax, Close, Exact, and Custom. Ignored for Interactive and CASS match modes.
Interactive match mode returns the best address regardless of this setting.
GS_FIND_RET_INTERSECTION_NUM
Type Boolean
Category AnyForward
GS_FIND_SUITELINK
Type Boolean
Category AnyForward
Usable match modes Relax, Interactive, Close, Custom and CASS. Exact match mode ignores this
setting.
GS_INIT_CACHESIZE
Type Long
Description Relative cache size used by GeoStan. Controls the amount of memory that GeoStan
allocates to store temporary street data during address processing. A smaller cache
may slow the performance of GeoStan. A cache size of 2 gives best performance,
but uses more memory.
Values 0,1, or 2.
Default value 1
GS_INIT_DATAPATH
Type String
Values
GS_INIT_DPV
Type Boolean
GS_INIT_GSVERSION
Type Long
Values
GS_INIT_LICFILENAME
Type String
Values
GS_INIT_OPTIONS_ADDR_CODE
Type Boolean
GS_INIT_OPTIONS_APN_CODE
Type Boolean
GS_INIT_OPTIONS_ELEVATION_CODE
Type Boolean
GS_INIT_OPTIONS_Z9_CODE
Type Boolean
GS_INIT_OPTIONS_ZIP_PBKEYS
Type Boolean
Description Open file needed to return PreciselyIDs for ZIP centroid locations in Master Location
Data.
When an address point is not available for an address in Master Location Data, this
option returns a ZIP centroid and the PreciselyIDunique identifier, which can be used
to unlock additional information about an address using GeoEnrichment data.
To enable returning PreciselyIDs for ZIP centroid locations in MLD, the
GS_FIND_Z_CODE GsFindWithProps property needs to be enabled. If it is
not enabled, an "E" location code is returned and the results data will not include a
geocode nor PreciselyID.
GS_INIT_OPTIONS_SPATIAL_QUERY
Type Boolean
GS_INIT_PASSWORD
Type Long
Values
GS_INIT_RELDATE
Type String
Values
GS_INIT_Z4FILE
Type String
Values
GS_INIT_DPV_DATA_ACCESS
Type Long
Description Indicates the type of files to load and how to access the files. The following table
contains the possible values.
Values • DPV_DATA_FULL_FILEIO - Files are not loaded into memory. Table access is
through file I/O.
• DPV_DATA_FULL_MEMORY - Files are loaded into memory. Use this option to
gain performance improvement by reducing repetitive file I/O.
• DPV_DATA_SPLIT_FILEIO - Use if your file is sorted by ZIP Code and you have
limited memory. Uses a split data format that separates the DPV data file into
multiple smaller files, based on the first 2 digits of the ZIP Code. If you sort your
mailing file by ZIP Code, you can use this value to bring the relevant portion of the
DPV file into memory. This process uses 32 MB of storage, but reduces the
number of I/O requests that normally occurs when you use the full DPV data file.
• DPV_DATA_FLAT_FILEIO - DPV flat file accessed via file I/O.
GS_INIT_DPV_DIRECTORY
Type String
GS_INIT_DPV_SECURITYKEY
Type String
Values
GS_INIT_FILE_MEMORY_LIMIT
Type Long
Description NOTE: This property only applies to 64-bit applications. For 32-bit applications,
data files are not memory-mapped and attempts to set this property will be ignored.
When GeoStan is initialized, it will memory-map as many data files into memory as
the GS_INIT_FILE_MEMORY_LIMIT allows. The default value of 16 GB is
sufficient for memory-mapping two streets and two points data sets. Memory
mapping your data files can provide a 10-15% performance improvement compared
to mapping none of them. However, if your environment has memory constraints, you
can set the GS_INIT_FILE_MEMORY_LIMIT to the number of megabytes you
can afford.
This initialization property can only be set once per GeoStan executable process. If
you attempt to set this property again (i.e., on a separate thread), the request is
ignored.
If all of the data files cannot be memory-mapped in the space provided, the status
property GS_STATUS_FILE_MEM_SYS_EXCDD is set to true. To see how much
virtual memory is being used for memory-mapping data files, query the status
property GS_STATUS_MEMORY_USED.
GS_INIT_GEOSTAN_ID
Type Long
GS_INIT_GS_ID
Type Pointer
Values
GS_INIT_LACSLINK_DIRECTORY
Type String
Values
GS_INIT_LACSLINK_SECURITY_KEY
Type String
Values
GS_INIT_RDI_DIRECTORY
Type String
Description Directory containing USPS Residential Delivery Indicator (RDI) data, max 255
characters. Requires Delivery Point Validation (DPV).
Values
GS_INIT_SUITELINK_DIRECTORY
Type String
Values
GS_STATUS_FILE_ALIAS
Type Boolean
GS_STATUS_FILE_APN
Type Boolean
GS_STATUS_FILE_AUXILIARY
Type Boolean
GS_STATUS_STATUS_BITFIELD
Type Long
Values
Default value
GS_STATUS_FILE_CENTRUS_ALIAS
Type Boolean
GS_STATUS_FILE_CITY_DIR
Type Boolean
GS_STATUS_DPV_FILE_ALL
Type Boolean
GS_STATUS_DPV_FILE_SECURITY
Type Boolean
GS_STATUS_FILE_ELEVATION
Type Boolean
GS_STATUS_FILE_EPI
Type Boolean
GS_STATUS_FILE_ERROR_INFO
Type Boolean
GS_STATUS_FILE_EWS
Type Boolean
GS_STATUS_FILE_EXPIRED
Type Boolean
GS_STATUS_FILE_GEO_DIR
Type Boolean
GS_STATUS_FILE_LICENSE
Type Boolean
GS_STATUS_FILE_LOT
Type Boolean
GS_STATUS_FILE_MEM_LIM_EXCDD
Type Boolean
GS_STATUS_FILE_MEM_SYS_EXCDD
Type Boolean
GS_STATUS_FILE_MEMORY_USED
Type Long
Values
Default value
Relation to deprecated
feature
GS_STATUS_FILE_MLD_EXTENDED_ATTR
Type Boolean
Description The Master Location Data Extended Attributes DLD files (extatt*p.dld) loaded
successfully.
GS_STATUS_FILE_PARSE_TABLES
Type Boolean
GS_STATUS_FILE_POI_IDX
Type Boolean
Description The optional POI Index file (poi.gsi) that contains firm, building and POI names
loaded successfully.
GS_STATUS_FILE_PREMIUM_POI_IDX
Type Boolean
Description The optional Premium POI Index files (ppoi1.gsi, 2.gsi, 3.gsi) that contain firm,
building and POI names loaded successfully.
GS_STATUS_FILE_POSTTYPE_XLAT
Type Boolean
GS_STATUS_FILE_REVERSE_PBKEY
Type Boolean
GS_STATUS_FILE_SPATIAL_QUERY
Type Boolean
GS_STATUS_FILE_STATE_XLAT
Type Boolean
GS_STATUS_FILE_UD
Type Boolean
GS_STATUS_FILE_ZCF_DIR
Type Boolean
GS_STATUS_FILE_ZIP_PBKEYS
Type Boolean
Description The ZIP centroid file (zipsmld.gsd) that contains PreciselyIDs loaded successfully.
GS_STATUS_FILE_ZIP4CENT_DIR
Type Boolean
GS_STATUS_FILE_ZIP9_IDX
Type Boolean
GS_STATUS_LACSLINK_FILE_ALL
Type Boolean
GS_STATUS_LACSLINK_FILE_SECUR
Type Boolean
GS_STATUS_RDI_FILE_ALL
Type Boolean
Syntax
GsFunStat GsCityDataGet (GsId gs, intlu rec, GsEnum which,
pstr pbuffer, int bufSize);
Arguments
GsEnum which Symbolic constant for the data item to retrieve. Input.
The following table lists the valid GsEnums for most languages and the returned data sizes
(including NULL characters).
GS_CITY_CTYSTKEY (7) Returns the 6-character USPS City State Key, which uniquely
identifies a locale in the city/state file.
GS_CITY_FACILITY (2) Returns the USPS City State Name Facility Code:
• A – Airport Mail Facility (AMF)
• B – Branch
• C – Community Post Office (CPO)
• D – Area Distribution Center (ADC)
• E – Sectional Center Facility (SCF)
• F – Delivery Distribution Center (DDC)
• G – General Mail Facility (GMF)
• K – Bulk Mail Center (BMC)
• M – Money Order Unit
• N – Non-Postal Community Name, Former Postal
Facility, or Place Name
• P – Post Office
• S – Station
• U – Urbanization
GS_CITY_IS_ABBREV (2) • Y - If the current record is the 13-character USPS city name.
• N - If the full city name.
GS_CITY_MAILIND (2) • Y – Can use City State Name as last line on a mail piece
• N – Cannot use City State Name as last line on a mail piece
GS_CITY_QCITY (10) City number; using the format ssffffccc, where s=state
number, f=finance number, and c=city number.
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsCityFindFirst() or GsCityFindNext()
Notes
The GsCityDataGet() function retrieves data about the city located with GsCityFindFirst()
or GsCityFindNext(). GeoStan derives city information from the USPS City/State file.
Example
See GsCityFindFirst for an example.
Finds the first city matching the partial name or valid ZIP Code.
Syntax
intlu GsCityFindFirst(GsId gs, gs_const_str State,
gs_const_str cityPattern);
Arguments
Return Values
Record number of the city located, or zero if GeoStan did not find any cities.
Prerequisites
GsClear()
Notes
This function retrieves the record number of the first city in a state that matches the city or
ZIP Code search string. For example if the entered state string is CA and the city string is S,
GeoStan finds the first city that begins with S in California. If the entered city string is 803
and the state string is null, GeoStan returns the first city in that sectional center. GeoStan
does not return cities in any predefined order.
Before each find function, call GsClear() to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
Example
/* This example prints all city names in the 803 sectional center. */
intlu CityRecNum;
char CityName[30];
GsClear(gs);
CityRecNum = GsCityFindFirst( gs, ““, “803” );
while (CityRecNum != 0 )
{
Syntax
intlu GsCityFindNext(GsId gs);
Arguments
Return Values
Record number of the located city, or zero if GeoStan did not find any cities.
Prerequisites
Notes
Call this function after GsCityFindFirst().
Before each find function, call GsClear() to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
Example
See GsCityFindFirst.
Syntax
GsFunStat GsClear(GsId gs);
Arguments
Return Values
GS_SUCCESS
GS_ERROR
Notes
Before each find function, call GsClear() to reset the internal buffers to null. If you do not
reset the buffers, you may receive incorrect results with information from a previous find.
This call clears only address element and location information about the previously
processed address and does not affect distance or centroid match type.
Syntax
GsFunStat GsDataGet(GsId gs, GsEnum fInOut, GsEnum fSwitch,
pstr pbuffer, intsu bufLen);
Arguments
GS_LASTLINE GS_ZIP4
GS_CITY GS_ZIP9
GS_STATE GS_ZIP10
GS_ZIP
If there is extra data on the input lastline (GS_LASTLINE), this data is not retrievable. For
example, in the lastline “BOULDER CO 80301 US OF A”, “US OF A” is not retrievable from
any GsDataGet() call.
To retrieve centerline return values, setting fInOut to GS_CENTERLINE returns a collection
of ranged segments for streets that contain addresses. Individual addresses may be
interpolated from the low-high ranges of the segments.
GsEnum fSwitch Symbolic constant for the data item to retrieve. Input.
intsu bufLen Maximum size of data for GeoStan to return. geostan.h lists
as constants the recommended buffer sizes for each item.
These sizes include the null terminator and are the maximum
lengths required to get the full output string. You can allocate
a buffer that is smaller or larger than these values. However, if
bufLen is shorter than the returned data, GeoStan truncates
the data and does not generate an error. Input.
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsFindWithProps()
Notes
This function retrieves data elements from internal GeoStan buffers for either the original
(input) or matched (output) data elements. To retrieve original data, set fInOut to GS_INPUT.
To retrieve matched data, set fInOut to GS_OUTPUT.
If your GeoStan license has metering enabled, using GsDataGet() to return a geocode
increments the counter unless the match code indicates an error or a 5-digit ZIP geocode.
Syntax
GsFunStat GsDataSet(GsId gs, GsEnum fSwitch, gs_const_str pBuffer);
Arguments
GsEnum fSwitch Symbolic constant for the data item to load. See “Enums for
storing and retrieving data” on page 96 for valid enums. Input.
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsInitWithProps()
Notes
This function loads data elements into internal GeoStan buffers. When loading address
information as a complete address or last line, GeoStan parses the data into fields. For
example, if you enter a last line of “Boulder, CO 80301-1234”, GeoStan parses the data and
sets the city, state, ZIP, and ZIP + 4 fields. You can retrieve parsed input data using
GsDataGet() with the GS_INPUT argument.
If you are passing both an address line and a last line or ZIP Code, enter the last line or ZIP
Code first to ensure the greatest accuracy in address standardization.
If you are passing both the address information and the last line information as one input
line, enter the address information first.
Using the appropriate GsEnums, you can pass single line addresses, two-line addresses,
or multiline addresses of up to six lines. For more information, see Appendix B: Extracting
Data from GSD Files.
Do not call alter the GS_FIND_MATCH_MODE property value in your Find Properties after you
have called GsDataSet(), because the previously established match mode affects how the
input address is parsed. If you need to change the match mode in mid-process, you must
re-enter the data for the current address with GsDataSet().
Obtains the complete DPV statistics since the application initialized DPV.
Syntax
GsFunStat GsDpvGetCompleteStats(GsId gs,
GsDPVCompleteStats* pdata,
int structSize);
Arguments
intlu nDPVTypeDValid Number of records with a confirmed primary house number, but the
secondary unit number is missing. Output.
intlu nDPVTypeSValid Number of records with a confirmed primary house number, but the
secondary unit number is not confirmed. Output.
intlu nFirmCMRAPresented Number of USPS Firm records with PMB presented. Output.
intlu nFirmCMRAValid Number of USPS Firm records CMRA confirmed with or without PMB.
Output.
intlu nFirmPrimeFail Number of USPS Firm records without a confirmed primary house
number. Output.
intlu nFirmSecondaryFail Number of USPS Firm records without a confirmed secondary unit
number. Output.
intlu nFootnoteAA Number of records with DPV footnote value AA. Output.
intlu nFootnoteA1 Number of records with DPV footnote value A1. Output.
intlu nFootnoteBB Number of records with DPV footnote value BB. Output.
intlu nFootnoteCC Number of records with DPV footnote value CC. Output.
intlu nFootnoteF1 Number of records with DPV footnote value F1. Output.
intlu nFootnoteM1 Number of records with DPV footnote value M1. Output.
intlu nFootnoteM3 Number of records with DPV footnote value M3. Output.
intlu nFootnoteN1 Number of records with DPV footnote value N1. Output.
intlu nFootnoteP1 Number of records with DPV footnote value P1. Output.
intlu nFootnoteP3 Number of records with DPV footnote value P3. Output.
intlu nFootnoteRR Number of records with DPV footnote value RR. Output.
intlu nFootnoteR1 Number of records with DPV footnote value R1. Output.
intlu nFootnoteU1 Number of records with DPV footnote value U1. Output.
intlu nHRCMRAPresented Number of USPS Highrise records with PMB presented. Output.
intlu nHRCMRAValid Number of USPS Highrise records with confirmed CMRA records with or
without PMB. Output.
intlu nHRPrimeFail Number of USPS Highrise records without a confirmed primary house
number. Output.
intlu nHRSecondaryFail Number of USPS Highrise records without a confirmed secondary unit
number. Output.
intlu nPOBoxFail Number of USPS PO Box records without a confirmed primary box
number. Output.
intlu nRRHCCMRAPresented Number of USPS Rural Route records with PMB presented. Output.
intlu nRRHCCMRAValid Number of USPS Rural Route records CMRA confirmed with or without
PMB. Output.
intlu nRRHCPrimeFail Number of USPS Rural Route records without a confirmed primary house
number. Output.
intlu nStCMRAPresented Number of USPS Street records with PMB presented. Output.
intlu nStCMRAValid Number of USPS Street records with CMRA confirmed with or without
PMB. Output.
intlu nStreetPrimeFail Number of USPS Street records without a confirmed primary house
number. Output.
intlu nStreetSecondaryFail Number of USPS Street records without a confirmed secondary unit
number. Output.
intlu nStreetValid Number of confirmed DPV records that matched to a USPS street record
(GS_REC_TYPE=S). Output.
Return Values
GS_SUCCESS
Prerequisites
GsInitDpv_r()
Syntax
GsFunStat GsDpvGetFalsePosDetail(GsId gs,
GsFalsePosDetailData* pdata,
int structSize);
Arguments
GsFalsePosDetailData* pdata
This structure retrieves the DPV detail record for the false-
positive address match using the data passed in
GsFalsePosDetailData. The data members are details
provided by GeoStan for the false-positive report. This
structure contains the following:
char AddressPrimaryNumber House number. Output.
Return Values
GS_SUCCESS
Prerequisites
GsInitDpv_r()
Syntax
GsFunStat GsDpvGetFalsePosHeaderStats(GsId gs,
GsFalsePosHeaderData *pdata,
int structSize);
Arguments
GsFalsePosHeaderData *pdata
This structure retrieves DPV statistics for the header record for false-positive
address matches using the data passed in GsFalsePosHeaderData. The
output values are statistics for the false-positive reports. The input values
include information to correctly complete the false-positive report for the
USPS. This structure contains the following:
intlu nTotalRecordsZIP4Matched Number of records that have matched with ZIP + 4. Output.
Return Values
GS_SUCCESS
GsInitDpv_r()
Syntax
GsFunStat GsErrorGet(GsId gs, pstr pMessage, pstr pDetail);
Arguments
pstr pMessage Basic explanation for the error; up to 256 bytes in length.
Output.
Return Values
Error number of the most recent GeoStan error.
-1 No error.
Alternates
GsErrorGetEx()
Syntax
void GsErrorGetEx(GsID id, pstr error_message, pstr details)
Arguments
pstr error_message
GeoStan error code and descriptive text. The error_message
has the following format: SGTppeeeDESCRIPTION, where:
SGT is a constant value.
pp is the product number (01 for GeoStan).
eee is the three character error code.
DESCRIPTION is a short text message naming the error.
pstr details Descriptive message, such as the file name associated with
the error.
Return values
The next GeoStan error detected in the current thread. Upon return, error messages
contain a brief description and additional text, such as the name of the file or directory
associated with the error.
Note: Not all errors are fatal. For example, if GeoStan finds an invalid data file, it reports the
error but continues executing.
Prerequisites
GsInitWithProps()
GsErrorHas()
Example
See GsInit_r for example code.
Indicates if any errors occurred or any informational messages are available in the current
thread.
Syntax
GsFunStat GsErrorHas(GsId id)
Arguments
Return Values
Prerequisites
GsInitWithProps()
Example
See GsErrorGetEx for example code.
Returns if the files successfully opened, and the date of the USPS data used in generating
the primary GSD file.
Syntax
intsu GsFileStatus(GsId gs, gs_const_str stateCode, intsu *date);
Arguments
gs_const_str stateCode
State FIPS or abbreviation (this argument is now ignored).
Input.
intsu *date Publish date of the USPS data used in the current GeoStan
release. Output.
Return Values
The return value is a series of bit-flags. The following GS_ENUMs are used to test these flags:
Prerequisites
GsInitWithProps()
Notes
The date argument indicates the creation date the primary GSD file. The date argument
and the GS_INIT_RELDATE initialization property value can be evaluated as follows:
Day date % 32
Example
/* This example tests for the primary GSD file and eLOT files. */
Syntax
intlu GsFileStatusEx(GsId gs, int mode, pstr buffer, int bufSize);
Arguments
int mode Specific information to return. The following table includes the
types of information available. Input.
See the Return Values section for information on the data types and datum returned.
GS_STATUS_DATUM_STR This is the NAD used natively by the data. It does not reflect
the datum currently in use by GeoStan. You can use the Find
property, GS_FIND_CLIENT_CRS, to set the returned NAD.
Returns GS_SUCCESS or GS_ERROR. The retrieved
information is placed in the buffer.
Return Values
This function returns a variety of information about the current GeoStan data set.
You can use the preceding arguments to determine the status of your GeoStan license, as
shown in the GsInitWithProps() code example.
0 USPS
1 TIGER
3 Sanborn point
4 Deprecated
9 Auxiliary file
10 User Dictionary
USPS USPS
TIGER TIGER
0 NAD27
Prerequisites
GsInitWithProps()
Syntax
GsFunStat GsFindFirstRange(GsId gs, GsRangeHandle *pRange);
GsFunStat GsFindFirstSegment(GsId gs, GsSegmentHandle *pSegment);
GsFunStat GsFindFirstStreet(GsId gs, GsStreetHandle *pStreet,
GsEnum option,
gs_const_str pLocale,
gs_const_str pName,
gs_const_str pNumber);
Arguments
GsRangeHandle *pRange
Pointer to a segment/range handle. Returns a valid handle if
GeoStan finds a range. Input, Output.
GsSegmentHandle *pSegment
Pointer to a street/segment handle. Returns a valid handle If
GeoStan finds a segment. Input, Output.
GsStreetHandle *pStreet
Pointer to a street handle. Returns a valid handle if GeoStan finds a street.
Output.
GS_ZIP_SEARCH GeoStan searches the ZIP Code specified by pLocale. When this option is set with
GsFindFirstStreet(), GeoStan performs a finance search.
GS_SDX_SEARCH GeoStan searches by soundex. pName is a pointer to a numeric soundex key returned
by GsSoundex. If you do not specify this option, GeoStan assumes that pName is a
street name.
gs_const_strpLocale
Sets the search area. If option is set to GS_ZIP_SEARCH, then
pLocale is a valid ZIP Code. If option is set to GS_CITY_SEARCH,
then pLocale is a valid city and state. GeoStan performs a city
search by searching all finance areas that cover that city. This
may result in found objects outside the actual city.Input.
gs_const_strpName
Street name, or partial street name, for which to search. If
option is set to GS_SDX_SEARCH, then pName is a pointer to a
numeric soundex key. Input.
This limits the search to street names that begin with the name string. If pName is “APPLE,”
then GeoStan returns only streets beginning with Apple, such as Apple or Appleton. If pName
is not specified, GeoStan finds all streets specified by pLocale.
gs_const_str pNumber
House number that must be within a range. If option is set to
GS_EXTRA_SEARCH, then pNumber must be blank. Input.
This returns only those ranges that contain that house number. This can be an alpha-
numeric house number, such as 12N123W.
Return Values
GS_ERROR Error occurred. You can retrieve the error using GsErrorGet.
GS_SUCCESS GeoStan found a match. You can retrieve the data using
GsHandleGet().
Notes
You must call GsFindFirstStreet() before GsFindFirstSegment() and
GsFindFirstSegment() before GsFindFirstRange(). GsFindFirstStreet() also sets the
area and criteria for subsequent segment and range searches.
If you are using GsFindFirstStreet() to find a street that has a number as a component of
the street name, such as “US HWY 41” or “I-95,” enter just the number, as the text is not
part of the index for such streets.
GsFindFirst___ and GsFindNext___ functions work together to allow you to access to the
entire address directory database.
See Appendix B: Extracting Data from GSD Files for more information on the Find First
functions and segment and range searches.
Note: GsFindFirstStreet() does not respect parity.
Example
/* This example searches ZIP Code 80301 for streets beginning with "A"
and no * specific house number. */
char tempstr[60];
GsStreetHandle hStreet;
GsSegmentHandle hSegment;
GsRangeHandle hRange;
hSegment.hStreet = hStreet;
hRange.hSegment = hSegment;
GsHandleGet(gs, GS_PREDIR, &hRange, tempstr,
sizeof(tempstr));
printf("Street: %s ", tempstr);
GsHandleGet(gs, GS_NAME, &hRange, tempstr, sizeof(tempstr));
printf("%s ", tempstr);
GsHandleGet( gs, GS_TYPE, &hRange, tempstr, sizeof(tempstr) );
printf("%s ", tempstr);
GsHandleGet(gs, GS_POSTDIR, &hRange, tempstr,
sizeof(tempstr));
printf( "%s\n", tempstr);
/* find the first valid segment for the current street*/
iStat = GsFindFirstSegment(gs, &hSegment);
Syntax
GsFunStat GsFindFirstSegmentByMbr(GsId gs, GsSegmentHandle *pSegment,
long lon1,
long lat1,
long lon2,
long lat2);
Arguments
GsSegmentHandle *pSegment
Pointer to a street/segment handle. Returns a valid handle if
GeoStan finds a segment. Input, Output.
long lon1 Minimum longitude. One of four values that make up the MBR.
Input.
long lat1 Minimum latitude. One of four values that make up the MBR.
Input.
long lon2 Maximum longitude. One of four values that make up the
MBR. Input.
long lat2 Maximum latitude. One of four values that make up the MBR.
Input.
Return Values
GS_ERROR Error occurred. You can retrieve the error using GsErrorGet().
GS_LASTLINE_NOT_FOUND
GeoStan could not find pSegment.
Prerequisites
Example
#include <stdio.h>
#include <string.h>
#define GEOSTAN_PROPERTIES
#include “geostan.h”
/* Initialization */
/* create an initialization property list with geostan information
*/
GsPropListCreate(&initProps, GS_INIT_PROP_LIST_TYPE);
/* GeoStan version */
GsPropSetLong(&initProps, GS_INIT_GSVERSION, GS_GEOSTAN_VERSION);
/* license filename and path */
GsPropSetStr(&initProps, GS_INIT_LICFILENAME,
"c:\\lic\\geostan.lic");
/* license file password */
GsPropSetLong(&initProps, GS_INIT_PASSWORD, 43218765);
/* path to the data files, geostan library, and GSX files*/
GsPropSetStr(&initProps, GS_INIT_DATAPATH,
"c:\\geostan\\datasets;c:\\geostan;c:\\temp");
/* path and file name of the zip code geocoding data file*/
GsPropSetStr(&initProps, GS_INIT_Z4FILE,
"c:\\geostan\\datasets\\us.z9");
/* GeoStan options */
GsPropSetBool(&initProps, GS_INIT_OPTIONS_ADDR_CODE, TRUE);
GsPropSetBool(&initProps, GS_INIT_OPTIONS_SPATIAL_QUERY, TRUE);
GsPropSetLong(&initProps, GS_INIT_CACHESIZE, 2);
gs = GsInitWithProps(&initProps, &statusProps);
if (!gs)
{
printf("Failed to initialize GeoStan library.\n");
return 1;
}
funStat = GsPrepareIndexMbr(gs, minLon, minLat, maxLon, maxLat,
gsxOutPath, "MBR index preparation: ", progress);
if ( funStat == GS_ERROR )
{
printf("GsPrepareIndexMbr returned GS_ERROR.\n");
return 1;
}
funStat = GsFindFirstSegmentByMbr(gs, &hSegment, minLon, minLat,
maxLon, maxLat);
while (funStat == GS_SUCCESS )
{
Syntax
GsFunStat GsFindFirstState (GsId gs, gs_const_str statePattern,
pstr stateFound, int bufSize);
Arguments
gs_const_str statePattern
Search string for the state. Input.
pstr stateFound Proper state abbreviation for the located state. Output.
Return Values
GS_ERROR
GS_SUCCESS
GS_NOT_FOUND
Notes
This function returns the proper abbreviation for the requested state. You can request states
by ZIP Code, full state name, or an alternate abbreviation
Before each find function, call GsClear() to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
Example
/* This example prints the official state abbreviation for ZIP Code
80301. */
char StateAbbr[3];
GsFunStat iStat;
Finds the first city, county, and or state centroid match from the set of possible matches
found.
Syntax
GsFunStat GsFindGeographicFirst(GsId gs, GsGeoStruct *gstruct);
Arguments
GsGeoStruct *gstruct
Pointer to the GsGeoStruct containing the input and output
fields for this API. Input, Output.
outRank Returned geographic rank of the city for city centroid. Output.
Return Values
GS_SUCCESS
GS_ERROR
GS_NOT_FOUND
GsInitWithProps()
Notes
It is recommended that the user first use the Last-line lookup functions to standardize the
city, county and state names. This function only performs minimal fuzzy matching on the
input city and county names. The location code returned by this function is to provide users
with a location code equivalent and is not retrievable using GsDataGet. It is merely provided
to offer a consistent label for the type of address match that is returned and will only consist
of one of the three Geographic location codes (GM – City, GC – County and GS – State).
Example
To use this API, you will use the following structure defined in geostan.h.
An example of using the Geographic Geocoding API is as follows. This assumes you have
a valid GsId named gs from a prior Geostan Initialization.
void GeographicGeocoding(GsId gs)
{
GsGeoStruct p;
int ret;
ret = GsFindGeographicFirst(gs,&p);
p.outCounty,p.outState,p.outResultCode,p.outLat,p.outLong);
if(strcmp(p.outResultCode,"G1")==0)
printf("%s \t %s \t %s \t %s \n",
p.outState,p.outResultCode,p.outLat,p.outLong);
printf("\n");
while(ret==0)
{
ret=GsFindGeographicNext(gs, &p );
if(ret == 0)
{
if(strcmp(p.outResultCode,"G3")==0)
printf("%s \t %s \t %s \t %s \t %s \n",
p.outCity,p.outState,p.outResultCode,p.outLat,p.outLong);
if(strcmp(p.outResultCode,"G2")==0)
printf("%s \t %s \t %s \t %s \t %s \n",
p.outCounty,p.outState,p.outResultCode,p.outLat,p.outLong);
if(strcmp(p.outResultCode,"G1")==0)
printf("%s \t %s \t %s \t %s \n",
p.outState,p.outResultCode,p.outLat,p.outLong);
printf("\n");
}
}
}
}
Finds the first city, county, and or state centroid match from the set of possible matches
found.
Syntax
GsFunStat GsFindGeographicFirstEx(GsId gs,
GsGeoStructEx* pGeoStruct);
Arguments
GsGeoStructEx* pGeoStruct
Pointer to the GsGeoStruct containing the input and output
fields for this API. Input, Output.
outRank Returned geographic rank of the city for city centroid. Output.
GS_SUCCESS
GS_ERROR
GS_NOT_FOUND
Prerequisites
GsInitWithProps()
Notes
It is recommended that the user first use the Last-line lookup functions to standardize the
city, county and state names. This function only performs minimal fuzzy matching on the
input city and county names. The location code returned by this function is to provide users
with a location code equivalent and is not retrievable using GsDataGet. It is merely provided
to offer a consistent label for the type of address match that is returned and will only consist
of one of the three Geographic location codes (GM – City, GC – County and GS – State).
Example
To use this API, you will use the following structure defined in geostan.h.
An example of using the Geographic Geocoding API is as follows. This assumes you have
a valid GsId named gs from a prior Geostan Initialization.
void GeographicGeocoding(GsId gs)
{
GsGeoStruct p;
int ret;
ret = GsFindGeographicFirst(gs,&p);
if(ret != 0)
printf("No record found");
else
{
if(strcmp(p.outResultCode,"G3")==0)
printf("%s \t %s \t %s \t %s \t %s \n",
p.outCity,p.outState,p.outResultCode,p.outLat,p.outLong);
if(strcmp(p.outResultCode,"G2")==0)
printf("%s \t %s \t %s \t %s \t %s \n",
p.outCounty,p.outState,p.outResultCode,p.outLat,p.outLong);
if(strcmp(p.outResultCode,"G1")==0)
printf("%s \t %s \t %s \t %s \n",
p.outState,p.outResultCode,p.outLat,p.outLong);
printf("\n");
while(ret==0)
{
ret=GsFindGeographicNext(gs, &p );
if(ret == 0)
{
if(strcmp(p.outResultCode,"G3")==0)
printf("%s \t %s \t %s \t %s \t %s \n",
p.outCity,p.outState,p.outResultCode,p.outLat,p.outLong);
if(strcmp(p.outResultCode,"G2")==0)
printf("%s \t %s \t %s \t %s \t %s \n",
p.outCounty,p.outState,p.outResultCode,p.outLat,p.outLong);
if(strcmp(p.outResultCode,"G1")==0)
printf("%s \t %s \t %s \t %s \n",
p.outState,p.outResultCode,p.outLat,p.outLong);
printf("\n");
}
}
}
}
Finds the next city, county, and or state centroid match from the set of possible matches
found.
Syntax
GsFunStat GsFindGeographicNext(GsId gs, GsGeoStruct *gstruct);
Arguments
GsGeoStruct *gstruct
Pointer to the GsGeoStruct containing the input and output
fields for this API. Input, Output.
outRank Returned geographic rank of the city for city centroid. Output.
Return Values
GS_SUCCESS
GS_ERROR
GS_NOT_FOUND
Prerequisites
GsInitWithProps()
Example
See the example for GsFindGeographicFirst.
Syntax
GsFunStat GsFindGeographicNextEx(GsId gs, GsGeoStructEx* pGeoStruct);
Arguments
GsGeoStructEx* pGeoStruct
Pointer to the GsGeoStruct containing the input and output
fields for this API. Input, Output.
outRank Returned geographic rank of the city for city centroid. Output.
Return Values
GS_SUCCESS
GS_ERROR
GS_NOT_FOUND
Prerequisites
GsInitWithProps()
Notes
It is recommended that the user first use the Last-line lookup functions to standardize the
city, county and state names. This function only performs minimal fuzzy matching on the
input city and county names. The location code returned by this function is to provide users
with a location code equivalent and is not retrievable using GsDataGet. It is merely provided
to offer a consistent label for the type of address match that is returned and will only consist
of one of the three Geographic location codes (GM – City, GC – County and GS – State).
Example
See the example for GsFindGeographicFirstEx.
Finds the next street, segment, or range object that meets the search criteria.
Syntax
GsFunStat GsFindNextRange(GsId gs, GsRangeHandle *pRange);
GsFunStat GsFindNextSegment(GsId gs, GsSegmentHandle *pSegment);
GsFunStat GsFindNextStreet(GsId gs, GsStreetHandle *pStreet);
Arguments
GsRangeHandle *pRange
Pointer to a segment/range handle. Returns a valid handle to
the next range object, if there is one. Input, Output.
GsSegmentHandle *pSegment
Pointer to a street/segment handle. Returns a valid handle to
the next segment object, if there is one. Input, Output.
GsStreetHandle *pStreet
Pointer to a street handle. Returns a valid handle to the next
street object, if there is one. Input, Output.
Return Values
GS_SUCCESS
GS_NOT_FOUND
GS_ERROR
Prerequisites
Notes
This function continues to find objects matching the criteria specified in GsFindFirst__.
If GeoStan finds a matching segment, you can retrieve the data using GsHandleGet().
Before each find function, call GsClear() to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
Refer to Appendix B: Extracting Data from GSD Files for details on using all of the
GsFindFirst___ and GsFindNext___ functions.
WIN UNIX
GsFindNextSegmentByMbr
Finds the next segment handle within the specified MBR.
Syntax
GsFunStat GsFindNextSegmentByMbr(GsId gs, GsSegmentHandle *pSegment);
Arguments
GsSegmentHandle *pSegment
Pointer to a segment handle. Returns a valid handle to the
next segment object, if there is one. Output.
Return Values
GS_ERROR Error occurred. You can retrieve the error using GsErrorGet.
Prerequisites
Notes
GeoStan handles all geocodes in the spatial query functions in ten-thousandths of
degrees—not millionths like GsDataGet().
Before each find function, call GsClear() to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
Example
See GsFindFirstSegmentByMbr for a code example.
Syntax
GsFunStat GsFindWithProps (GsId gs, PropList* pProps);
Arguments
PropList* pProps
Pointer to property list structure. Input.
Return Values
GS_ADDRESS_NOT_RESOLVED
GeoStan cannot resolve a match candidate.
GS_ADDRESS_NOT_FOUND
GeoStan did not find an address match or if you have a
metered license and the GeoStan record count is depleted.
For metered licenses, GsFind decrements the GeoStan record counter in the license each
time it returns a non-error match code. If the counter reaches zero or below, GsFind returns
GS_ADDRESS_NOT_FOUND and sets the match code to E015. If you have an unmetered license,
no decrementing occurs, and processing is unlimited.
GS_LASTLINE_NOT_FOUND
GeoStan did not find a match for city/state or ZIP Code.
GS_NOT_FOUND GeoStan did not find a match for an input PreciselyID with
Reverse PreciselyID Lookup.
Prerequisites
GsPropListCreate()
GsPropSet*()
Notes
The application owns the property list, but GeoStan is the active user.
Do not destroy the property list while GeoStan is still using that property list.
See table “GsFindWithProps properties” on page 122.
Syntax
GsFunStat GsFormatCASSHeader(GsId gs,
GsExtendCASSData *pData,
int dataSize,
pstr headerBuffer,
int bufSize);
Arguments
GsExtendCASSData *pData
Writes the CASS information to the header buffer using the
data passed in GsExtendCASSData. This structure contains the
following (lengths are in brackets):
char CASS_Z4CompanyName[40] Name of the company requesting certification. Input.
char DPV_FileFormat DPV date file format: F - Full, S - Split, and L - Flat. Input.
char LOT_DPCCompanyName[40] Name of the company requesting eLOT & DPC Utility
certification. Input.
char templateName[256] Full path and name of cass3553.frm template file. Input.
pstr headerBuffer Buffer containing the CASS header line from the Stage file.
Input, Output.
Return Values
GS_SUCCESS
Prerequisites
GsInitWithProps()
Notes
When you specify a version number for either version, z4ChangeVersion or LOTVersion,
GeoStan updates the corresponding fields in the header buffer similar to
GsWriteExtendCASSReport. For example, entering a version number for z4ChangeVersion
prompts GeoStan to fill the following fields in cass3553.frm:
• Section “B. List”, Item “2b”: Date List Processed Z4Change
• Section “B. List”, Item “3b”: Date of Database Product Used Z4Change
• Section “C. Output”, Item “1b”: Total Coded Z4Change Processed
To develop CASS certified applications in GeoStan, you must have the correct license
agreement with Pitney Bowes. You must also obtain CASS certification from the USPS for
your application. Using GeoStan does not make an application CASS certified. For
information on becoming CASS certified, refer to Appendix E: CASS certification overview
This data is defined in geostan.h in the data structure GsExtendCASSData.
Example
/* assign outCASSHeader flag to process->writeCASSHeader */
/* open address input file */
/* if writeCASSHeader flag is set to 1 read and store headerline first
*/
/* otherwise ignore it */
if(process->writeCASSHeader == 1)
{
process->headerBuffer = (pstr)malloc(process->inRecLen + 1);
Syntax
GsFunStat GsFormatDpvFalsePosDetail(GsId gs,
GsDpvFalsePosDetailData *pData,
int structSize,
pstr detail,
int detailLength);
Arguments
GsDpvFalsePosDetailData *pData
Pointer to the DPV report data structure. This value is
completed by GsDpvGetFalsePosDetail().
pstr detail Buffer containing the DPV false-positive detail record after
GsFormatDpvFalsePosDetail() successfully completes. When
the GeoStan application writes the false-positive report, it
writes this buffer to the last line of the file. Output.
Return Values
GS_SUCCESS
Prerequisites
GsDpvGetFalsePosDetail()
Syntax
GsFunStat GsFormatDpvFalsePosHeader(GsId gs,
GsFalsePosHeaderData *pData,
int structSize,
pstr header,
int headerLength);
Arguments
GsFalsePosHeaderData *pData
Pointer to the DPV report data structure. This value is
completed by GsDpvGetFalsePosHeaderStats(). Input.
Return Values
GS_SUCCESS
Prerequisites
GsDpvGetFalsePosHeaderStat()
Syntax
GsFunStat GsFormatLACSFalsePosDetail(GsId gs,
GsFalsePosDetailData *pData,
int structSize,
pstr detail,
int detailLength);
Arguments
GsFalsePosDetailData *pData
Pointer to the LACSLink report data structure. This value is completed by
GsLACSGetFalsePosDetail(). Input.
pstr detail Buffer containing the LACSLink false-positive detail record after
GsFormatLACSFalsePosDetail() successfully completes.
When the GeoStan application writes the false-positive report,
it writes this buffer to the last line of the file. Output.
Return Values
GS_SUCCESS
Prerequisites
GsLACSGetFalsePosDetail()
Syntax
GsFunStat GsFormatLACSFalsePosHeader(GsId gs,
GsFalsePosHeaderData *pData,
int structSize,
pstr header,
int headerLength);
Arguments
GsFalsePosHeaderData *pData
Pointer to the LACSLink report data structure. This value is
completed by GsLACSGetFalsePosHeaderStats(). Input.
Return Values
GS_SUCCESS
Prerequisites
GsLACSGetFalsePosHeaderStats()
Syntax
ints GsGetCoordsEx(GsId gs, pintl pCoords, intsu maxPoints);
Arguments
Return Values
Number of points assigned to buffer.
Prerequisites
GsFindWithProps()
Notes
This function returns an array of coordinates for the current feature found via GsFind().
GeoStan can return a maximum of 64 coordinate pairs, each pair consisting of two long
integers.
Pass in a value of 2 for the maxPoints parameter in order to return the end points of the
segment matched.
GeoStan returns the coordinates to the full precision stored in the GSD file and scales
coordinate pairs to integers. For example, GeoStan returns a point at (-98.3, 29.7) as
(983000, 297000). This is a different scale from that expected by Spatial+ and similar GIS
applications, which typically express coordinates in millionths of degrees. You may need to
scale coordinates obtained with this function before using them as input to other software
libraries or applications.
Populates the supplied buffer with the information about the item being queried for the
specified database.
Syntax
ints GsGetDBMetadata(GsId gs, int WhichItem, int WhichDB, pstr buffer,
int bufSize);
Arguments
GS_STATUS_DATUM_STR This is the NAD used natively by the data. It does not
reflect the datum currently in use by GeoStan. See
GS_FIND_CLIENT_CRS for further
information on setting the NAD for geocoding.
Returns GS_SUCCESS or GS_ERROR. The retrieved
information is placed in the buffer.
int WhichDB A database index, starting at 0 and less than the number of
databases returned by GsGetNumDB(). Input.
int bufSize Maximum size of data for GeoStan to return. Geostan.h lists
as constraints the recommended buffer sizes for each item.
These sizes include the null terminator and are the maximum
lengths required to get the full output string. You can allocate
a buffer that is smaller or larger than these values. However, if
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsInitWithProps()
Syntax
GsFunStat GsGetLibVersion( );
Arguments
None.
Return Values
Prerequisites
GsInitWithProps()
Notes
In general, the major version number changes whenever Precisely adds a new API
features, or when the data structures in the GeoStan data files change.
Syntax
GsFunStat GsGetMbr(GsId gs, GsEnum which, void *pData,
long *pMinLong, long *pMinLat, long *pMaxLong,
long *pMaxLat);
Arguments
GsEnum which The following table contains the possible values to which
GeoStan assumes pData is pointing.
GS_MBR_SEGMENT GsSegmentHandle.
GS_MBR_STREET GsStreetHandle.
GS_MBR_FINANCE pstr, containing digits in the format SSFFFF where S is state, and F is
finance
long pMinLong Minimum longitude. One of four values that make up the MBR.
Output.
long pMinLat Minimum latitude. One of four values that make up the MBR.
Output.
long pMaxLong Maximum longitude. One of four values that make up the
MBR. Output.
long pMaxLat Maximum latitude. One of four values that make up the MBR.
Output.
Return Values
Notes
GeoStan handles all geocodes in these functions in ten-thousandths of degrees—not
millionths like GsDataGet().
To make a call with GS_MBR_CITY, you must first make a call to GsPrepareIndexFinance(). To
retrieve an MBR for GS_MBR_CITY, you must have already installed from the data media, or
built the uscity.gsx file using the batchind.exe utility program. Use GsDataGet() with
GS_QCITY to get a city number or a finance number (finance number is the first 6 digits of the
city number).
Syntax
intlu GsGetNumDB(GsId gs);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsInitWithProps()
Syntax
GsFunStat GsHandleGet(GsId gs, GsEnum fSwitch,
GsRangeHandle *pRange, pstr pBuffer,
intsu bufLen);
Arguments
GsEnum fSwitch Enum for the argument you wish to retrieve. Input.
GsRangeHandle *pRange
Pointer to the current range handle. Input.
intsu bufLen Maximum size of the data that GeoStan returns. If bufLen is
shorter than the data returned by GeoStan, GeoStan truncates
the data and does not generate an error. Input.
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsFindFirst() or GsFindNext()
Notes
This function retrieves data from the geocode buffer for a given range handle. If you have a
street or segment handle, you must convert the handle to a range handle before you can
use this function.
See Appendix B: Extracting Data from GSD Files for more information on the Find First and
Find Next searches. For information on extracting Alias information, refer to the description
in GsMultipleGet().
Retrieves the coordinates for a street segment object found via GsFindFirst() and
GsFindNext().
Syntax
ints GsHandleGetCoordsEx(GsId gs, GsSegmentHandle *pHandle,
pintl pCoords, intsu maxPoints);
Arguments
GsSegmentHandle *pHandle
Handle of the segment object for the coordinates returned.
Input.
Return Values
Number of points assigned to the buffer.
Prerequisites
GsFindFirst() or GsFindNext()
Notes
This function returns an array of coordinates for the segment to which handle points.
GeoStan can return a maximum of 64 coordinate pairs, each pair consisting of two long
integers.
Pass in a value of 2 for the maxPoints parameter in order to return the end points of the
segment matched.
Example
/*This example retrieves coordinates for a street segment found using
GsFindFirstSegment.*/
#define MAX_POINTS 50
.
.
.
ints NumCoords;
intl Coords[MAX_POINTS *2];
Syntax
GsId GsInitWithProps(PropList* pInitProps, PropList* pStatusProps);
Arguments
PropList* pInitProps*
Pointer to property list structure of type
GS_INIT_PROP_LIST_TYPE. Input.
PropList* pStatusProps
Pointer to property list structure of type
GS_STATUS_PROP_LIST_TYPE. Output.
Return Values
Returns the ID of the GeoStan instance that was initialized.
Prerequisites
Notes
Initializes GeoStan using the property list. The application owns the property lists. The
status property list is guaranteed to contain properties for all defined status properties with
their values properly set.
GsInitWithProps can be used to initialize GeoStan, DPV, and LACSLink with a single call (if
the appropriate initialization properties are in the init list). When this function successfully
completes, it populates the GS_INIT_GS_ID property in the property list referred to by the
pInitProps parameter with the actual GeoStan ID.
If you invoke this function with the GeoStan ID property pre-set to a valid GeoStan ID, it will
not attempt to re-initialize GeoStan. This is how GsInitWithProps() can be used to initialize
DPV and/or LACSLink after GeoStan has already been initialized with a previous call to
GsInitWithProps(). If you intend to reuse the same initialization property list to initialize
GeoStan several times you must reset the GS_INIT_GS_ID property back to zero, or
completely remove the property from the list. This informs GeoStan that you want a new
GeoStan instance when you call GsInitWithProps().
These initialization properties are required for GsInitWithProps to function correctly:
• GS_INIT_LICFILENAME
Deprecation note:
On 32-bit systems, GsInitWithProps() will also populate the GS_INIT_GEOSTAN_ID with the
GeoStan ID. However, the same is not true for 64-bit systems. As a result, the
GS_INIT_GEOSTAN_ID property has been deprecated. Instead, use the GS_INIT_GS_ID
property for getting/setting the GeoStan ID.
Example
GsFunStat retval;
PropList initProps;
PropList statusProps;
GsPropListCreate( &initProps, GS_INIT_PROP_LIST_TYPE);
GsPropListCreate( &statusProps, GS_STATUS_PROP_LIST_TYPE);
GsPropSetStr( &initProps, GS_INIT_LICFILENAME,
"c:\\test\\Data\\my.lic");
GsPropSetStr(&initProps, GS_INIT_DATAPATH, "c:\\test\\Data" );
GsPropSetStr(&initProps, GS_INIT_Z4FILE, ""c:\\test\\Data\\us.z9" );
GsPropSetLong(&initProps, GS_INIT_PASSWORD, 12345678 );
GsPropSetLong(&initProps, GS_INIT_GSVERSION, GS_GEOSTAN_VERSION );
GsPropSetBool(&initProps, GS_INIT_OPTIONS_ADDR_CODE, TRUE );
GsPropSetBool(&initProps, GS_INIT_OPTIONS_Z9_CODE, TRUE );
GsPropSetBool(&initProps, GS_INIT_OPTIONS_SPATIAL_QUERY, TRUE );
GsPropSetBool(&initProps, GS_INIT_OPTIONS_APN_CODE, TRUE );
GsPropSetBool(&initProps, GS_INIT_OPTIONS_ELEVATION_CODE, TRUE );
GsPropSetLong(&initProps, GS_INIT_CACHESIZE, 0 );
GsPropSetBool(&initProps, GS_INIT_ENABLE_AIRPORT, TRUE );
GsPropSetBool(&initProps, GS_INIT_ENABLE_HIGHWAY_EXIT, TRUE );
GsPropSetLong(&initProps, GS_INIT_FILE_MEMORY_LIMIT, 4000 );
GsPropSetLong(&initProps, GS_INIT_GEOSTAN_ID, 0 ); // not required,
but demonstrates the usage.
gs = GsInitWithProps(&initProps, &statusProps);
Syntax
GsFunStat GsLACSClearStats(GsId gs,
GsLACSCompleteStats *pStats,
int structSize);
Arguments
GsLACSCompleteStats *pdata
This structure retrieves LACSLink statistics since the application
initialized LACSLink. This structure contains the following:
Return Values
GS_SUCCESS
Prerequisites
Obtains the complete LACSLink statistics since the application initialized LACSLink.
Syntax
GsFunStat GsLACSGetCompleteStats(GsId gs,
GsLACSCompleteStats *pdata,
int structSize);
Arguments
GsLACSCompleteStats *pdata
This structure retrieves LACSLink statistics since the application
initialized LACSLink. This structure contains the following:
Return Values
GS_SUCCESS
Prerequisites
Syntax
GsFunStat GsLACSGetFalsePosDetail(GsId gs,
GsFalsePosDetailData *pdata,
int structSize);
Arguments
GsFalsePosDetailData *pdata
This structure retrieves the LACSLink detail record for false-
positive address match using the data passed in
GsFalsePosDetailData. The data members are details
provided by GeoStan for the false-positive report. This
structure contains the following:
Return Values
GS_SUCCESS
Syntax
GsFunStat GsLACSGetFalsePosHeaderStats(GsId gs,
GsFalsePosHeaderData *pdata,
int structSize);
Arguments
GsFalsePosHeaderData *pdata
This structure retrieves the LACSLink header record for false-
positive address matches using the data passed in
GsFalsePosHeaderData. The output data members are
statistics for the false-positive report. The input data members
include information to correctly complete the false-positive
report for the USPS. This structure contains the following:
Return Values
GS_SUCCESS
Prerequisites
Syntax
GsFunStat GsMultipleGet(GsId gs, GsEnum fSwitch, ints index,
pstr pBuffer, intsu bufLen);
Arguments
GsEnum fSwitch Enum for the argument you want to retrieve. Input.
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsNumMultiple()
Notes
This function retrieves data from the GeoStan buffer for match candidates. GeoStan
indicates a match candidate as the GS_ADDRESS_NOT_RESOLVED return code for
GsFindWithProps.() It is important to first test for an intersection match, since the enums are
different for retrieving intersection and non-intersection matches.
If you use GS_ALIAS with an enum that does not return alias information (such as GS_ZIP),
GeoStan returns the information in the normal format. If GS_IS_ALIAS returns A07, you can
only get information based on the returned address, not the alias.
Note: GsMultipleGet() index zero output is different from the GsDataGet().
When using GsDataGet(), returned results may be altered for the best match based on all
the candidates found. GsMultipleGet() however does not change the results but provides
raw data for the returned candidates. Therefore, some enums may differ from
GsMultipleGet() and GsDataGet(). For example, GS_ADDRLINE, only contains information
available from the candidate data records. If there is no unit low-high on the candidate, no
unit information is added to the GS_ADDRLINE.
The following enums are different if the GsDataGet() spatial information is inferred against
another candidate in the list:
GS_LAT GS_LON
GS_LOC_CODE
These enums differ when CASS logic decides the city/zip/zip+4 on the GsDataGet() lastline
versus pure candidate information used for GsMultipleGet():
GS_CITY GS_CITY_SHORT
GS_LASTLINE GS_MM_RESULT_CODE
GS_MATCH_CODE GS_NAME_CITY
GS_URB_NAME GS_ZIP
GS_ZIP_CARRTSORT GS_ZIP_CITYDELV
GS_ZIP_CLASS GS_ZIP_FACILITY
GS_ZIP_UNIQUE GS_ZIP4
GS_ZIP9 GS_ZIP10
These enums differ when information from the input carries over on the GsDataGet() versus
pure candidate information used for GsMultipleGet():
GS_ADDRLINE GS_FIRM_NAME
GS_UNIT_TYPE
Example
/* This example prints information about possible matches. It assumes
that GsFindWithProps returned GS_ADDRESS_NOT_RESOLVED. */
char buffer[60];
int bInter;
printf( "Possibles:\n" );
/* Test for match candidate and set bInter to non-zero if true. */
GsMultipleGet( gs, GS_INTERSECTION, 0, buffer,
sizeof(buffer) );
bInter = *buffer == 'T';
/* Get the number of multiples and print them as we loop through each
one. */
int n = GsNumMultiple( gs );
for ( int i = 0; i < n; ++i )
{
printf( "%d: ", i );
/* If we don't have an intersection, print the ranges. */
if ( !bInter )
{
GsMultipleGet( gs, GS_LORANGE, i, buffer, sizeof(buffer) );
printf( "%s ", buffer );
GsMultipleGet( gs, GS_HIRANGE, i, buffer, sizeof(buffer) );
printf( "%s ", buffer );
}
/* Print the street name for both intersections and non
intersections.*/
GsMultipleGet( gs, GS_PREDIR, i, buffer, sizeof(buffer) );
printf( "%s ", buffer );
GsMultipleGet( gs, GS_NAME, i, buffer, sizeof(buffer) );
printf( "%s ", buffer );
GsMultipleGet( gs, GS_TYPE, i, buffer, sizeof(buffer) );
printf( "%s ", buffer );
GsMultipleGet( gs, GS_POSTDIR, i, buffer, sizeof(buffer) );
printf( "%s ", buffer );
/* If an intersection match, print the second street name. */
if ( bInter )
{
printf( " AT " );
GsMultipleGet( gs, GS_PREDIR2, i, buffer, sizeof(buffer) );
printf( "%s ", buffer );
GsMultipleGet( gs, GS_NAME2, i, buffer, sizeof(buffer) );
printf( "%s ", buffer );
GsMultipleGet( gs, GS_TYPE2, i, buffer, sizeof(buffer) );
printf("%s", buffer );
GsMultipleGet( gs, GS_POSTDIR2, i, buffer, sizeof(buffer) );
printf( "%s ", buffer );
}
/* Print each possible on a new line. */
printf( "(%s)\n", buffer );
}
Syntax
GsFunStat GsMultipleGetHandle(GsId gs,
ints index,
GsRangeHandle *pHandle);
Arguments
GsRangeHandle *pHandle
Range handle for the possible match entry. Output.
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsNumMultiple()
Notes
This function can extract additional information about a possible match than
GsMultipleGet(). It retrieves the range handle for the possible match indicated by the entry
argument. Once you have the correct range handle, you can retrieve information by using
GsHandleGet(). For a list of elements returned by GsMultipleGet() or GsHandleGet(), see
“Enums for storing and retrieving data” on page 96.
Syntax
GsFunStat GsNumMultiple(GsId gs);
Arguments
Return Values
Positive value indicates the number of match candidates. GS_ERROR indicates an error.
Prerequisites
GsFind()
Notes
This function returns the number of match candidates found. Use GsMultipleGet() to
retrieve the actual address elements for each possible match. A return code from
GsFindWithProps() indicates a possible match.
Example
See “GsMultipleGet” on page 224.
Syntax
GsFunStat GsPrepareIndexFinance(GsId gs,
long finance,
const char *outDir,
void *progressData,
spatialQueryProgress progress);
Arguments
long finance Finance area to index. In the format ssffff, where s=state
and f=finance. Input.
spatialQueryProgress progress
Callback function for progress meter. If NULL GeoStan does
not call progress. Input.
Return Values
GS_SUCCESS
GS_ERROR
GS_NOT_FOUND More than 6 digits were entered for the finance parameter.
Prerequisites
GsCityDataGet()
Notes
Prepares the reverse geocoding system for searching the requested finance area, unlike
PrepareIndexMbr(), which prepares the system for each finance area included partially or
wholly within the area bounded by the four input points. See PrepareIndexMbr for more
information.
Call before GsFindFirstSegmentByMbr().
In addition, when using GsInitWithProps() include the outDir directory in the search path.
For example, C:\data;C:\gsxout, where C:\data contains the primary data files and
C:\gsxout is the output directory for GSX files. Include finmbr.dat in the GsInitWithProps()
search path when creating GSX files.
See GsPrepareIndexMbr for more information on the progress function.
WIN UNIX
GsPrepareIndexMbr
Prepares GSX files needed to cover the MBR.
Syntax
GsFunStat GsPrepareIndexMbr(GsId gs,
long lon1,
long lat1,
long lon2,
long lat2,
const char *outDir,
void *progressData,
spatialQueryProgress progress);
Arguments
long lon1 Minimum longitude. One of four values that make up the MBR.
Input.
long lat1 Minimum latitude. One of four values that make up the MBR.
Input.
long lon2 Maximum longitude. One of four values that make up the
MBR. Input.
long lat2 Maximum latitude. One of four values that make up the MBR.
Input.
spatialQueryProgress progress
Callback function for progress meter. If NULL GeoStan does
not call progress. Input.
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsInitWithProps()
Notes
Prepares the reverse geocoding system for each Finance Area needed to cover the MBR
specified by the four lat/lon parameters.
Call before GsFindFirstSegmentByMbr().
Note: This function expects that you have either installed the prebuilt GSX file that ships
on the data media or that you have already created the GSX file using the
batchind.exe utility included with GeoStan. For more information, refer to the
GeoStan Geocoding Suite Utilities Manual.
For proper execution, initialize GeoStan with a call to GsInitWithProps and include at least
the following properties set to TRUE:
GS_INIT_OPTIONS_ADDR_CODE
GS_INIT_OPTIONS_SPATIAL_QUERY
GS_INIT_OPTIONS_Z9_CODE
In addition, when using GsInitWithProps() include the outDir directory in the search path.
For example, C:\data;C:\gsxout, where C:\data contains the primary data files and
C:\gsxout is the output directory for .gsx files. Include finmbr.dat in the
GsInitWithProps() search path when creating .gsx files.
Example
See “GsFindFirstSegmentByMbr” on page 186 for an example.
intl mode One of three values in the following table. Value contents vary
depending on mode.
0 Initialize progress meter. Return GS_PROGRESS_CONTINUE or
value is estimated total number of GS_PROGRESS_CANCEL.
steps.
Syntax
GsFunStat GsPropFind(PropList* pProps, PropEnum pPropID);
Arguments
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsPropListCreate()
Notes
GS_SUCCESS returns if the property is found in the property list. GS_ERROR returns if the
property is not found.
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetBool(&findProps, GS_FIND_MIXED_CASE, TRUE);
retval = GsPropFind(&findProps, GS_FIND_Z9_CODE);
retval = GsPropFind(&findProps, GS_FIND_MIXED_CASE);
Syntax
GsFunStat GsPropFirst(Proplist* pProps);
Arguments
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsPropListCreate()
Notes
Prior to iterating through the properties in a property list, this function sets the property list
iterator to the beginning of the list.
Example
GsFunStat retval;
PropList findProps;
PropEnum propID;
PropValue propValue = {GS_UNDEF_PROP_TYPE, 0};
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetBool(&findProps, GS_FIND_MIXED_CASE, TRUE);
retval = GsPropSetLong(&findProps, GS_FIND_MATCH_MODE,
GS_MODE_CLOSE);
retval = GsPropSetLong(&findProps, GS_FIND_STREET_OFFSET, 50);
GsPropFirst(&findProps );
while (GsPropGetNext(&findProps, &propID, &propValue) == GS_SUCCESS
) {
switch (propValue.propType) {
case GS_BOOL_PROP_TYPE:
...
break;
case GS_LONG_PROP_TYPE:
...
break;
case GS_STRING_PROP_TYPE:
...
break;
case GS_DOUBLE_PROP_TYPE:
case GS_UNDEF_PROP_TYPE:
default:
Syntax
GsFunStat GsPropGetBool (PropList* pProps, PropEnum propID,
qbool *pbValue);
Arguments
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsPropListCreate()
Syntax
GsFunStat GsPropGetDouble (PropList* pProps, PropEnum propID,
double *pdValue);
Arguments
Return Values
GS_SUCCESS
Prerequisites
GsPropListCreate()
Syntax
GsFunStat GsPropGetInfo(PropEnum propID, int* pPropType,
PropListType* pPropListType,
pstr pPropName, int* pPropCategory);
Arguments
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsPropListCreate()
Syntax
GsFunStat GsPropGetLong(Proplist* pProps, PropEnum propID,
intl *plValue);
Arguments
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsPropListCreate()
Example
GsFunStat retval;
PropList findProps;
long lValue;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetLong(&findProps, GS_FIND_MATCH_MODE,
GS_MODE_CLOSE);
retval = GsPropGetLong(&statusProps, GS_FIND_MATCH_MODE, &lValue);
Syntax
GsFunStat GsPropGetNext(Proplist* pProps, PropEnum* propID,
PropValue pPropValue);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Notes
GeoStan only populates one of the PropValue union members. The populated union
member depends on the property output type. If there is no “next” entry, GeoStan returns an
error.
Example
See GsPropFirst example.
Syntax
GsFunStat GsPropGetPtr(PropList* pProps, PropEnum propID,
void *pValue);
Arguments
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsPropListCreate()
Syntax
GsFunStat GsPropGetStr(Proplist* pProps, PropEnum propID,
pstr pBuffer, intsu bufLen);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
GsPropListCreate()
Example
GsFunStat retval;
PropList findProps;
char buffer[256];
const int bufLen = 256;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetStr(&findProps, GS_FIND_CLIENT_CRS, "NAD83");
retval = GsPropGetStr(&findProps, GS_FIND_CLIENT_CRS, buffer,
bufLen);
Syntax
GsFunStat GsPropGetStrLen (Proplist* pProps, PropEnum propID,
intlu bufLen);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites()
GsPropListCreate()
Syntax
GsFunStat GsPropListClear(PropList* pProps);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetBool(&findProps, GS_FIND_Z_CODE, TRUE);
retval = GsPropSetLong(&findProps, GS_FIND_STREET_OFFSET, 50);
retval = GsPropListClear(&findProps);
Notes
You may want to clear a property list for re-populating from the beginning with new
properties.
Creates and initializes a property list to contain GeoStan initialization, status, or find
properties.
Syntax
GsFunStat GsPropListCreate (Proplist* pProps, PropListType type);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Notes
This function creates/initializes a property list for use in GsInitWithProps() or
GsFindWithProps(). Any property list created by this function needs to eventually be
destroyed with GsPropListDestroy().
Example
GsFunStat retval;
PropList initProps;
PropList statusProps;
PropList findProps1;
PropList findProps2;
Syntax
GsFunStat GsPropListDestroy (Proplist* pProps);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Notes
Find property lists cannot be destroyed until all searching is complete. Any list created by
GsPropListCreate() must eventually be destroyed with GsPropListDestroy().
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate( &findProps, GS_FIND_PROP_LIST_TYPE );
retval = GsPropListDestroy ( &findProps );
Syntax
GsFunStat GsPropListGetCount (Proplist* pProps, intl* pCount);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Example
intl count;
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropListGetCount(&findProps, &count);
Syntax
GsFunStat GsPropListGetType(Proplist* pProps, PropListType* pType);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Example
GsFunStat retval;
PropList findProps;
PropListType type;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropListGetType(&findProps, &type);
Syntax
GsFunStat GsPropListRead(Proplist* pProps, gs_const_str infile,
gs_const_str pBuffer);
Arguments
gs_const_str infile
File containing the list properties, or NULL. Input.
s_const_strpBuffer
String buffer containing the properties to read if infile is NULL.
Input.
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Notes
If the infile argument value is “stdin”, then this function reads the properties from standard
in. If the infile argument is NULL, then this function reads the properties from the pBuffer
string.
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropListRead(&findProps, "testprop.txt", NULL);
Syntax
GsFunStat GsPropListReset(PropList* pProps);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Notes
Depending on the type of property list, this might mean “empty” (init and status properties)
or refill it with some needed defaults (find properties).
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetBool(&findProps, GS_FIND_Z_CODE, TRUE);
retval = GsPropSetLong(&findProps, GS_FIND_STREET_OFFSET, 50);
retval = GsPropListReset(&findProps);
Syntax
GsFunStat GsPropListWrite(PropList* pProps, gs_cont_str outfile,
pstr pBuffer, intsu bufLen);
Arguments
gs_cont_str outfile
File containing the list properties, or NULL. Output.
intsu bufLen Length of pBuffer (writing should not exceed bufLen). Input.
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Notes
If the outfile argument value is “stdout”, then this function writes the properties to standard
out. If the outfiles argument is NULL, then this function writes the properties to the pBuffer
string.
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetBool(&findProps, GS_FIND_Z_CODE, TRUE);
retval = GsPropSetLong(&findProps, GS_FIND_STREET_OFFSET, 50);
retval = GsPropListWrite(&writeProps, "testprop.txt", NULL, 0);
Syntax
GsFunStat GsPropRemove(PropList* pProps, PropEnum propID);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetBool(&findProps, GS_FIND_Z_CODE, TRUE);
retval = GsPropRemove(&findProps, GS_FIND_Z_CODE);
Sets a property where input name and value are both strings.
Note: If you intend to use the same Find property settings for all your address records, try
to construct your application to set the Find properties once before processing. It is
unnecessary to reset the properties again to the same values for each address
record. However, if required, you can change Find property values for individual
searches. Performance may be negatively affected by resetting for individual record
searches. Reset Find properties between address searches only if changing the Find
property value is necessary.
Syntax
GsFunStat GsPropSetAsStr(PropList* pProps, gs_const_str pszPropName,
PropEnum propID, gs_const_str pszValue);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Notes
This function performs the conversion to correct property enum ID and property value type.
If the input property name is a NULL pointer, the property ID is for use in identifying the
property instead. If both property name and property ID are present, preference is given to
the property name, ignoring the property ID.
Example
GsFunStat retval;
PropList initProps;
retval = GsPropListCreate(&initProps, GS_INIT_PROP_LIST_TYPE);
retval = GsPropSetAsStr(&initProps, "GS_INIT_PASSWORD",
GS_UNDEFINED_PROPID, "12345678");
retval = GsPropSetAsStr(&initProps, NULL, GS_INIT_PASSWORD,
"12345678");
Syntax
GsFunStat GsPropSetBool(PropList* pProps, PropEnum propID,
qbool value);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetBool(&findProps, GS_FIND_MIXED_CASE, TRUE);
Syntax
GsFunStat GsPropSetDouble (PropList* pProps, PropEnum propID,
double value);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Note: If you intend to use the same Find property settings for all your address records, try
to construct your application to set the Find properties once before processing. It is
unnecessary to reset the properties again to the same values for each address
record. However, if required, you can change Find property values for individual
searches. Performance may be negatively affected by resetting for individual record
searches. Reset Find properties between address searches only if changing the Find
property value is necessary.
Syntax
GsFunStat GsPropSetLong (PropList* pProps, PropEnum propID,
intl value);
Arguments
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetLong(&findProps, GS_FIND_MATCH_MODE, GS_MODE_CASS);
Syntax
GsFunStat GsPropSetPtr(PropList* pProps, PropEnum propID,
void *pValue);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate
Syntax
GsFunStat GsPropSetStr (PropList* pProps, PropEnum propID,
gs_const_str value);
Arguments
Return Values
GS_ERROR
GS_SUCCESS
Prerequisites
GsPropListCreate()
Example
GsFunStat retval;
PropList findProps;
retval = GsPropListCreate(&findProps, GS_FIND_PROP_LIST_TYPE);
retval = GsPropSetStr(&findProps, GS_FIND_CLIENT_CRS, "NAD83");
Syntax
GsFunStat GsSetSelection(GsId gs, ints index);
Arguments
Return Values
GS_SUCCESS
Prerequisites
GsMultipleGet()
Notes
After GsFindWithProps() returns GS_ADDRESS_NOT_RESOLVED, use GsNumMulitple() and
GsMultipleGet() to determine which possible match is the correct match. Then use
GsSetSelection() to load that possible match into the data retrieval buffers and retrieve it
using GsDataGet().
Note: GsSetSelection() and GsSetSelectionRange() functions should only be called
once per address find (i.e. GsFindWithProps). Also, these functions should only
be called if the find resulted in a match candidate (match code = E023).
Example
/* This example prints information about possible matches. It assumes
that GsFind returned GS_ADDRESS_NOT_RESOLVED. */
char buffer[60];
int bInter;
printf( "Possibles:\n" );
/* Test for match candidate and set bInter to non-zero if true. */
GsMultipleGet( gs, GS_INTERSECTION, 0, buffer,
sizeof(buffer) );
bInter = *buffer == 'T';
/* Get the number of multiples and print them as we loop through each
one. */
int n = GsNumMultiple( gs );
for ( int i = 0; i < n; ++i )
{
printf( "%d: ", i );
/* If we don't have an intersection, print the ranges. */
int index = 0;
GsFunStat funStat;
printf(" Please enter selection number.");
scanf("%i", &index);
if (funStat == GS_SUCCESS)
{
GsDataGet( gs, GS_OUTPUT, GS_FIRM_NAME, firm, sizeof(firm) );
GsDataGet( gs, GS_OUTPUT, GS_ADDRLINE, address, sizeof(address) );
GsDataGet( gs, GS_OUTPUT, GS_LASTLINE, lastline, sizeof(lastline) );
GsDataGet( gs, GS_OUTPUT, GS_LON, longitude, sizeof(longitude) );
GsDataGet( gs, GS_OUTPUT, GS_LAT, latitude, sizeof(latitude) );
printf( "%s\n"
"%s\n"
"%s\n"
"longitude: %lf\n"
"latitude: %lf\n", firm, address, lastline, /* ascii data */
(double)(atof(longitude)/1000000.0), /* normalize longitude */
(double)(atof(latitude)/1000000.0) ); /* normalize latitude */
}
else
printf("Address information not found.");
Syntax
GsFunStat GsSetSelectionRange(GsId gs, GsRangeHandle *pRange,
GsEnum options);
Arguments
GsRangeHandle *pRange
Range pointer of the object to return as a match. A range record indicates a
range of addresses such as “2800 - 2900 Center Green Drive”. Input.
GS_WIDE_SEARCH GeoStan considers all records matching the first letter of the street
name, rather than the soundex key on the street name. This results in
a wider search.
GS_Z9_CODE Attempts to find ZIP + 4 centroid match only (no ZIP+2 or ZIP).
GS_Z7_CODE Attempts to find ZIP+2 centroid match only (no ZIP + 4 or ZIP).
GS_Z_CODE Attempts to find a match based on all possible ZIP centroids available.
If you specify GS_ADDR_CODE and a ZIP centroid option, GeoStan only returns a ZIP Code
centroid match if an address geocode is not available.
You must use either GS_ADDR_CODE or GS_Z_CODE or both.(In general, you should specify
both.) These option settings are additive.
If you enter a pre-parsed address, it must contain the USPS abbreviations for street type,
predirectionals, and postdirectionals.
Return Values
GS_SUCCESS
GS_ERROR
GsFindFirstRange()
Notes
This function allows you to get a range handle that points to the address range to which you
want to match. Use this command to indicate that GsFindWithProps() found the match,
when in fact the match is set to whichever range handle is passed through the *pRange
argument. You must specify the options enum so that subsequent calls to GsDataGet()
have the type of location information to return.
This function returns standardized results from a list generated by GsFindFirst/GsFindNext.
Use this function to perform a query that lets the user choose from a list of possible
matches.
Note: GsSetSelection() and GsSetSelectionRange() functions should only be called
once per address find (i.e. GsFindWithProps()). Also, these functions should only
be called if the find resulted in multiple candidates for a match (match code =
E023).
Syntax
intlu GsSoundex(pstr pName);
Arguments
Return Values
Soundex key.
Notes
Note: A soundex match is a match based on the pronunciation of a field.
This function generates a soundex key for a street name. Use it in conjunction with
GsFindFirstStreet() when you want to perform a soundex search. The soundex key, when
combined with a locale (state, and city), is the primary index into the GeoStan databases.
Searching by soundex allows you to use your own scoring and matching mechanism for
geocoding.
GeoStan uses a modified version of the standard soundex algorithm first published by
Donald Knuth. The modifications employed within GeoStan include special treatment of
certain prefixes such as MAC, KN, and WR; numeric street names; and an encoding
scheme to pack the key into the smallest number of bits.
Terminates GeoStan.
Syntax
GsFunStat GsTerm(GsId gs);
Arguments
Return Values
GS_SUCCESS
GS_ERROR
Notes
You must call GsTerm() at the conclusion of a session to close files and release other
resources. It closes GeoStan and invalidates GsId.
You cannot call any function that accepts a GsId parameter except GsInit_r following a call
to GsTerm. Also, you should only delete the initialization, find, and status properties (by
calling GsPropListDestroy) that you have used with GeoStan after the call to GsTerm.
Syntax
GsFunStat GsTestRange(GsId gs, gs_const_str number,
gs_const_str rangeLo, gs_const_str rangeHi);
Arguments
Return Values
Prerequisites
GsInitWithProps()
Notes
GsTestRange() tests to see if the house number is within the range defined by rangeHi and
rangeLo. It handles all valid house number patterns, such as:
12 12 A1 1A A1
3 3A 23 23 B2
3
1A 1- AB
23 23
B
This function uses USPS rules defined in Publication 28, “Postal Addressing Standards,” to
determine if a number is in range. For more information, refer to this publication on the
USPS Website.
Some patterns are not comparable with other patterns; for example, 123 is not comparable
to a range of 1A01 to 1A99.
Note: GsTestRange() does not respect parity.
Syntax
GsFunStat GsVerifyAuxiliaryRecord (GsId gs, const char *pRecord)
Arguments
Return Values
GS_SUCCESS The record is valid and GeoStan will load the record. This
includes comment records; records whose first character is a
semicolon.
GS_WARNING The record contains a non-fatal error and GeoStan will load
the record. Because this record has a problem, an input
address may not be able to match to the record in its current
state, or the output data from a match to the record may not be
valid.
GS_ERROR The record contains a fatal error and GeoStan will NOT load
the file.
Prerequisites
GsInitWithProps()
Example
char buffer[800];
char msg1[GS_MAX_STR_LEN], msg2[GS_MAX_STR_LEN];
FILE * fp;
GsId gs;
GsFunStat rc;
int recno = 0;
Syntax
GsFunStat GsVerifyGSDDataPresent (GsId gs, GsStateList states)
Arguments
Return Values
GS_GSD_DATA_MISSING
One or more states or FIPS codes specified in states are not
present in GSD data.
Prerequisites
You must create a valid GsId with a call to GsInitWithProps().
If GeoStan did not find the GSD primary data for all the specified states, this function
creates an error in the error list retrievable using GSErrorGetEx. The error message code is
114 and the error message is “NO GSD DATA FOUND FOR STATE” and indicates which states
GeoStan did not find.
FIPS FIPS
State Abbrev. Codea State Abbrev. Codea
Colorado CO 8 Ohio OH 39
Connecticut CT 9 Oklahoma OK 40
Delaware DE 10 Oregon OR 41
Idaho ID 16 Tennessee TN 47
Illinois IL 17 Texas TX 48
Indiana IN 18 Utah UT 49
Iowa IA 19 Vermont VT 50
Kansas KS 20 Virginia VA 51
Kentucky KY 21 Washington WA 53
Maine ME 23 Wisconsin WI 55
Maryland MD 24 Wyoming WY 56
Michigan MI 26 Guam GU 66
Mississippi MS 28 Palau PW 70
Nebraska NE 31
Nevada NV 32
New Hampshire NH 33
a Do not specify Minor Islands (UM, 74) or you will receive an error. This is defined as a FIPS
code, but the USPS does not generate data for this code.
The following pseudo FIPS codes support APO and FPO addresses:
Example
typedef struct GsStateList
{
char state[100][3]; /* array of 2 char null terminated strings */
int cnt; /* entries in 'state' that are filled in */
}
GsStateList;
GsStateList states;
char error_buffer[256];
char details_buffer[256];
/* note that test for CASS required GSD data is not a fatal error so
the 'error' flag is not set */
states.cnt = 0;
strcpy(states.state[states.cnt++], "AL");
strcpy(states.state[states.cnt++], "AK");
strcpy(states.state[states.cnt++], "AZ");
/* additional states can be copied into the array here */
....
strcpy(states.state[states.cnt++], "AA");
Syntax
GsFunStat GsWriteExtendCASSReport (GsId gs, GsExtendCASSData *pData,
int dataSize,
gs_const_str outputName);
Arguments
GsExtendCASSData *pData
The structure allows you to specify the name of the template
form. This structure is also defined in geostan.h. This function
writes a CASS Report using the data passed in
GsExtendCASSData. Input.
char DPV_FileFormat DPV date file format: F - Full, S - Split, and L - Flat. Input.
Return Values
GS_SUCCESS
GS_ERROR
Prerequisites
GsInitWithProps()
Notes
Before running a CASS report, verify GeoStan has loaded the GSU, USPS.gdi, and GSZ
files (ZIPMove data).
Note: See Appendix E: CASS certification overview for an example of a CASS 3553
form and more information on obtaining CASS certification.
When you specify a version number for either version, Z4ChangeVersion or LOTVersion,
GeoStan updates the corresponding fields in the template cass3553.frm file. For example,
entering a version number for Z4ChangeVersion prompts GeoStan to fill these fields on
cass3553.frm:
Example
/* get the file status and file Date of required files */
fileRet = GsFileStatus(process->gs, fileStateCode, &fileDate);
CASSData.nRecs = report.records;
strcpy( CASSData.listName, outListName );
strcpy( CASSData.pSearchPath, process->searchPath );
strcpy( CASSData.LOTVersion, CASSData.version );
strcpy( CASSData.CASS_Z4CompanyName, "Pitney Bowes" );
strcpy( CASSData.LOT_DPCCompanyName, "Pitney Bowes" );
strcpy( CASSData.CASS_Z4Config, "CAS" );
strcpy( CASSData.LOT_DPCConfig, "CAS" );
strcpy( CASSData.CASS_Z4SoftwareName, programName );
CASSData.zip4DatabaseDate = fileDate;
CASSData.LOTDatabaseDate = fileDate;
}
.
.
.
/* calculate nRecs, nZip, nZip4... and set these in the CASSData
structure */
Geocode( )
.
.
.
/* write the CASS report from data in CASSData structure */
retval = GsWriteExtendCASSReport( process->gs, &CASSData, sizeof(
CASSData ), process->CASSFile );
Determines if the USPS changed a ZIP + 4 address definition since GeoStan last
processed the record.
Syntax
GsFunStat GsZ4Changed (GsId gs, pstr pZip, pstr pZip4, pstr pDate);
Arguments
pstr pZip First five digits of the 9-digit ZIP Code to test. Input.
pstr pZip4 Last four digits of the 9-digit ZIP Code to test. Input.
pstr pDate Date of the GeoStan ZIP + 4 information file used to process
the record, in the format MMYYYY (for example, 081998). Input.
Return Values
GS_ERROR Usually occurs when GeoStan could not load the GSL file,
because:
GeoStan could not find the GSL file in the path
The GSL file was a different release level than the GSD file.
GS_Z4_CHANGE
GS_Z4_NO_CHANGE
Prerequisites
GsInitWithProps()
Notes
For ZIP4Change to work, the GeoStan GSL file must be in a directory listed in the
GS_INIT_DATAPATH initialization property of the property list that you pass when calling
GsInitWithProps. The Z4Change file, which is generated by the USPS, contains a record for
every ZIP + 4 in the country. Each record contains twelve flags that represent the last twelve
months, starting with the current release date. Each of these flags has a value of either True
or False, indicating if the ZIP + 4 changed for that monthly postal release. The GeoStan
GSL file incorporates this information, which GsZ4Changed references.
Z4Change information is valuable to users who process very large address lists frequently.
As you process each record, you can call GsZ4Changed and quickly tell if the record needs
reprocessing. This information can help you quickly identify only those records that need
reprocessing.
Example
intsu postalDate;
int month, year;
char z4ChangeDate[7];
/* Get the postal release of the current files. */
GsFileStatus ( gs,"", &postalDate );
month = ((postalDate % 384) / 32) + 1;
year = (postalDate/384) + 1990;
/* Add one month to this date so it matches what is printed on the CD.
*/
if ( month !=12 )
{
++month;
}
else
{
++year;
month = 1;
}
/* Print the month and year to the date string in the format MMYYYY. */
sprintf( z4changedate, "%02d%d", month, year );
In this chapter
This chapter lists the public functions in alphabetical order. The
following sections provide a quick reference to the data types,
copybooks, and procedures; organized by usage.
Variables
GSFSTAT
Returns if the file successfully opened, and the date of the USPS data used in generating
the primary GSD file.
GSFSTATX
Returns a variety of information about the current GeoStan data set and license.
GSGLIBV
Returns the current version of the GeoStan library.
GSINITWP
Initializes GeoStan.
GSSCACHE
Sets the size of the cache GeoStan uses.
GSSLIC
Identifies license file and key.
GSSRELD
Allows you to specify the oldest acceptable date for GeoStan data files.
GSTERM
Terminates GeoStan.
GSCITYDG
Retrieves data for the found city record.
GSCITYFF
Finds the first city matching partial name or valid ZIP Code.
GSCITYFN
Finds the next matching city.
GSFFSTAT
Finds the first state matching name, abbreviation, or valid ZIP Code.
Address lookup
GSDATGET
Returns data for all address and matched elements from GeoStan.
GSDATSET
Passes data for all address elements to GeoStan.
GSFFRANG
Finds the first range object that meets the search criteria.
GSFFSEG
Finds the first segment that meets the search criteria.
GSFFST
Finds the first street object that meets the search criteria.
GSFNRANG
Finds the next range object that meets the search criteria.
GSFNSEG
Finds the next segment that meets the search criteria.
GSFNST
Finds the next street that meets the search criteria.
GSGCRDX
Retrieves coordinates for the street segment found via GSFINDWP.
GSMGET
Returns the address elements for the match candidate item specified.
GSMGH
Returns the range handle for the match candidate item specified.
GSNMULT
Returns the number of match candidates found.
GSSETSEL
Allows you to select a match from a set or match candidatees.
Data querying
GSDBMETA
Retrieves coordinates for the street segment found via GSFINDWP.
GSGETNDB
Returns the number of loaded databases.
GSHGCRDX
Retrieves the coordinates for a street segment object found via GSFFSEG and
GSFNRANG.
GSHGET
Retrieves data for objects found via GSFFSEG and GSFNRANG.
GSERRGET
Retrieves current error information.
GSERRHAS
Indicates if any errors occurred or any informational messages are available in the current
thread.
GSSSELR
Allows GeoStan to use a record found outside of GSSFINDWP as a match.
GSFGF
Finds the first geographic information record with partial matching to input names.
GSFGFX
Finds the first city, county, and or state centroid match from the set of possible matches
found.
GSFGN
Finds the next geographic information record with partial matching to input names.
GSFGNX
Finds the next city, county, and or state centroid match from the set of possible matches
found.
Utilities
GSCLEAR
Clears the data buffer in the internal data structures.
GSSNDX
Generates a soundex key for use in GSFFSEG.
GSTSTRNG
Tests if a house number falls within a range.
GSVAUXR
Validates an auxiliary file record.
GSZ4CH
Determines if the USPS changed a ZIP + 4 address definition since GeoStan last
processed the record.
GSFCASSH
Writes a CASS 3553 report to the header buffer argument.
GSWECASS
Writes a USPS CASS report based on the specified template.
GSDPVGCS
Obtains the complete DPV statistics since the application initialized DPV.
GSDPVGFD
Retrieves the detail record for a DPV false positive report.
GSDPVGFH
Retrieves DPV statistics for the header record for a DPV false positive report.
GSFDFPD
Formats a DPV false positive detail record from GSDPVGFD.
GSFDFPH
Formats a DPV false positive header record with data from GSDPVGFD.
GSLACCLS
GSLACFPD
Formats a LACSLink false positive header record with data from GSLACGFH.
GSLACGCS
Obtains the complete LACSLink statistics since the application initialized LACSLink.
GSLACGFD
GSLACGFH
Retrieves LACSLink statistics for the header record for a LACSLink false positive report.
GSPSETAS
Sets a property where input name and value are both strings.
GSPSETB
Sets a boolean property.
GSPSETD
Sets a double property.
GSPSETL
Sets an integer property.
GSPSETS
Sets a short integer property.
GSPSETST
Sets a string property.
GSPGETB
Retrieves a boolean property.
GSPGETD
Retrieves a double property.
GSPGETST
Retrieves a string property.
GSPGINFO
Retrieves information about a property.
GSPGSTRL
Retrieves the length of the string value of a property.
GSPFIND
Finds a property in a property list.
GSPFIRST
Sets property iterator to first property.
GSPFNEXT
Iterates to the next sequential property in the property list.
GSPLSTCR
Creates and initializes a property list for GeoStan initialization.
GSPLSTDE
Destroys a property list.
GSPLSTGC
Retrieves the number of properties in a property list.
GSPLSTWR
Writes the property list to a file or a character string.
GSPREMOV
Removes a property from the property list.
GSPRESET
Resets the property list to its default state.
GSHGET • Street
A bullet indicates this variable is valid when using a Street handle with
GSHGET. Includes only Street level information.
• Segment
A bullet indicates this is valid when using a Segment handle with
GSHGET. Includes Street and Segment information.
• Range
A bullet indicates this variable is valid when using a Range handle with
GSHGET. Includes Street, Segment, and Range information.
GSDATGET • Input
A bullet indicates this is valid when using input flag with this function.
• Output
Indicates this variable is valid when using the output flag with this
function. Can be:
– A – Valid for non-intersection matches only
– I – Valid for intersection matches only
– L - Valid for street locator matches only
– P - Centrus point data match.
– R - Reverse geocoding only.
– Bullet – Valid for all types of match
Length A number indicating the largest string GeoStan returns for this variable.
This length includes a NULL-termination character. Symbolic constants
use the naming convention <<NAME>>-LENGTH. For example the
variable GS-ADDRLINE returns the input or output address line. The
maximum length of an address line is 61. Therefore, the symbolic constant
is GS-ADDRLINE-LENGTH and is defined as 61.
GS-ADDRLINE 61
First address line or address line for single line addresses.
For single line addresses, enter address line and last line
combined as a single input, for example,
“4750 Walnut St 80301”.
GS-ADDRLINE-SHORT 61
Shortest possible address line that can be constructed from
available short street name and the other address line
components.
GS-ADDR2 61
Second address line.
GS-ADDRTYPE 2 A,P A,P
Address Type regarding number of units:
• S – Single unit
• M – Multiple units
• P – Post Office box
• X – Unknown
GS-BLOCK 16 A A
15-digit census block ID/census FIPS code, using the syntax
sscccttttttgbbb where:
• ss – 2-digit State FIPS Code
• ccc – 3-digit County FIPS Code
• tttttt – 6-digit Census Tract FIPS Code
• g – Single-digit Block Group FIPS Code, and
• bbb – Block FIPS Code
If the address is on the left side of the street, GS-BLOCK will
contain the equivalent of GS-BLOCK-LEFT. If the address is
on the right, GS-BLOCK will contain the equivalent of GS-
BLOCK-RIGHT.
GS-BLOCK-RIGHT 16 A
Census block ID from the right side of the street.
GS-BLOCK-RIGHT2 16 I
GS-BLOCK-RIGHT for the second segment in the intersection.
GS-BLOCK-SFX 2 A
Current block suffix for Census 2010 geography.
GS-BLOCK-SFX-LEFT 2
Current left block suffix for Census 2010 geography.
GS-BLOCK-SFX-LEFT2 2 I
GS-BLOCK-SFX-LEFT for the second segment in the
intersection.
GS-BLOCK-SFX-RIGHT 2
Current right block suffix for Census 2010 geography. Blank if
the matched record is from point-level data.
GS-BLOCK-SFX-RIGHT2 2 I
GS-BLOCK-SFX-RIGHT for the second segment in the
intersection.
GS-CART 5 A A
Carrier route.
GS-CBSA-DIVISION-NAME 128
CBSA division name.
GS-CBSA-DIVISION-NAME2 128 I
GS-CBSA-DIVISION-NAME for the second segment in the
intersection.
GS-CBSA-DIVISION-NUMBER 6
CBSA division number.
GS-CBSA-DIVISION-NUMBER2 6 I
GS-CBSA-DIVISION-NUMBER for the second segment in the
intersection.
GS-CBSA-NAME 128
CBSA name.
GS-CBSA-NAME2 128 I
GS-CBSA-NAME for the second segment in the intersection.
GS-CBSA-NUMBER 6
CBSA number.
GS-CBSA-NUMBER2 6 I
GS-CBSA-NUMBER for the second segment in the intersection.
GS-CHECKDIGITb 2
Check digit.
GS-CITY 29
Abbreviated city name from the last line of the input or output
address; the value from GS-NAME-CITY or GS-PREF-CITY.
GS-CITY-SHORT 29
The output city name that appears in GS_LASTLINE_SHORT.
This value is determined by logic similar to GS_CITY.
Whenever possible, this city name is 13 characters or less.
This output city name is determined by CASS rules. This can
be either City State Name, City State Name Abbreviation, or
Preferred Last Line City State Name.
GS-CLOSE-MATCH
Indicates if the address was a Close match.
• T - Match candidate is a Close match to the input address.
• F - Match candidate is not a Close match to the input
address.
GS-CMSA 81
CMSA name.
GS-CMSA-NUMBER 5
CMSA number.
GS-COUNTY 6
County FIPS code. (For GSHGET and GSMGET this is the
USPS county for the Range record. For GSDATAGET this is the
county from the segment record or the USPS county if matched
to a USPS only range.)
GS-COUNTY2 6 I
GS-COUNTY for the second segment in the intersection.
GS-COUNTY-FIPS 4
County FIPS code
GS-COUNTY-NAME 128
County name.
GS-COUNTY-NAME2 128 I
GS-COUNTY-NAME for the second segment in the
intersection.
GS-CSA-NAME 128
CSA name.
GS-CSA-NAME2 128 I
GS-CSA-NAME for the second segment in the intersection.
GS-CSA-NUMBER 4
CSA number.
GS-CSA-NUMBER2 4 I
GS-CSA-NUMBER for the second segment in the intersection.
GS-CTYST-KEY 7
USPS city state key (an alphanumeric value that uniquely
identifies a locale in the USPS city state product).
GS-DATATYPE 3
Type of data used to make the match.
• 0 – USPS data
• 1 – TIGER data
• 2 – TomTom street-level data
• 3 – Sanborn point-level data
• 4 – Deprecated
• 5 – Deprecated
• 6 – HERE (formerly NAVTEQ) street-level data
• 7 – TomTom point-level data
• 8 – Centrus point-level data
• 9 – Auxiliary file data
• 10 – User Dictionary
• 11 – HERE (formerly NAVTEQ) point-level data
• 12 – Master Location Data
GS-DATATYPE2 3 I
GS-DATATYPE for the second segment in the intersection.
GS-DFLTb 2 A
Indicates the return status of GS-HI-RISE-DFLT and GS-R-
RTE-DFLT
• Y – Either GS-HI-RISE-DFLT or GS-R-RTE-DFLT
returned Y.
• Blank – Both GS-HI-RISE-DFLT and GS-R-RTE-DFLT
returned N or Blank.
GS-DPBCb 3
Delivery Point Bar Code.
GS-DPV-CONFIRM 2
Indicates if a match occurred for DPV data.
• N – Nothing confirmed
• Y – Everything confirmed (ZIP + 4, primary, and secondary)
• S – ZIP + 4 and primary (house number) confirmed
• D – ZIP + 4 and primary (house number) confirmed and a
default match (GS-HI-RISE-DFLT = Y), secondary did
not confirm.
• Blank – non-matched input address to USPS ZIP + 4 data,
or DPV data not loaded
GS-DPV-CMRA 2
DPV CMRA indicator.
• Y – Address found in CMRA table
• N – Address not found in CMRA table
• Blank – DPV not loaded
GS-DPV-FALSE-POS 2
DPV false-positive indicator.
• Y – False-positive match found
• Blank – False-positive match not found
GS-DPV-FOOTNOTE1 3
Information about matched DPV records.
• AA – ZIP + 4 matched
• A1 – Failure to match a ZIP + 4
• Blank – Address not presented to hash table or DPV data
not loaded
GS-DPV-FOOTNOTE2 3
Information about matched DPV records.
• BB – All DPV categories matched
• CC – DPV matched primary/house number, where the
secondary/unit number did not match (present but invalid)
• M1 – Missing primary/house number
• M3 – Invalid primary/house number
• N1 – DPV matched primary/house number, with a missing
secondary number
• P1 – Missing PS, RR, or HC Box number
• P3 – Invalid PS, RR or HC Box number
• F1 – All military addresses
• G1 – All general delivery addresses
• U1 – All unique ZIP Code addresses
• Blank – Address not presented to hash table or DPV data
not loaded
GS-DPV-NO-STAT 2
• Y - The address is valid for CDS pre-processing.
• N - The address is not valid for CDS pre-processing.
• Blank - DPV is not loaded or DPV did not confirm.
GS-DPV-SHUTDOWN 2
• Y - Address was found in false-positive table.
• N - Address was not found in false-positive table.
• Blank - Address was not presented to hash table or DPV
data not loaded.
GS-DPV-VACANT 3
• Y - The address is vacant.
• N - The address is not vacant.
• Blank - DPV is not loaded or DPV did not confirm (so
vacancy is irrelevant).
GS-EWS-MATCH 2
Indicates if GeoStan made an EWS match.
• Y – Match denied because it matched to EWS data.
• Blank – Input record did not match to EWS data.
GS-FIRM-NAME 41 A A
Name of firm from the USPS data or the input firm name.
GS-GOVT-FLAG 2 A
Government building indicator.
• A – City government building
• B – Federal government building
• C – State government building
• D – Firm-only
• E – City government building and firm only
• F – Federal government building and firm only
• G – State government building and firm only
A, B, C, E, F, and G are valid for alternate records only (GS-
ALT-FLAG=A). D is valid for both base and alternate records.
GS-HI-RISE-DFLT 2 A
Indicates if GeoStan matched to a highrise.
• N – Matched to an exact highrise record or a street record
• Y – Did not match to an exact record. Matched to the USPS
default highrise record or a street record. Check the input
address for accuracy and completeness.
• Blank – Does not apply to the input address (for example,
PO Boxes and General Delivery addresses) or did not find
a match.
GS-HIRANGE 12 A A
House number at high end of range.
GS-HIUNIT 12 A A
High unit number.
GS-HIZIP4 5 A
High ZIP + 4 for this range.
GS-HOUSE-NUMBER 12 A
House number of input or output address.
GS-HOUSE-NUMBER2 12 A
Second house number for a ranged house number match. If
GS_FIND_ADDRESS_RANGE is enabled, the second
number in the ranged address.
GS-INC-IND 2 A,P A,P
Incorporated Place Indicator.
• I – Incorporated place
• N – Not an incorporated place
• X – Unknown
GS-IS-ALIAS 4 A
The first character is:
• N – Normal street match
• A – Alias match (including buildings, aliases, firms, etc.)
The next 2 characters are:
• 01 – Basic index, normal address match
• 02 – USPS street name alias index
• 03 – USPS building index
• 05 – Statewide intersection alias (when using the
Usw.gsi, Use.gsi,or US.gsi file).
• 06 – Spatial data street name alias (when using the
Us_pw.gsi, Usw.gsi, Us_pe.gsi, Use.gsi,
Us_ps.gsi, Usp.gsi, Us_psw.gsi, or Us_pse.gsi
file is required.)
• 07 – Alternate index (when using Zip9.gsu, Zip9e.gsu,
and Zip9w.gsu)
• 08 – LACSLink
• 09 – Auxiliary file match.
• 10 – Centrus Alias index (when using usca.gsi)
• 11 – POI index (when using poi.gsi)
• 12 – USPS Preferred Alias
• 13 – ZIPMove match (when using us.gsz)
• 14 – Expanded Centroids match (when using
us_cent.gsc)
GS-LACS-FLAG 2 A
Indicates if GeoStan marked the address for conversion.
• L – Address marked for LACS conversion.
• Blank – Address not marked for LACS conversion.
GS-LACSLINK-IND 2
LACSLink indicator.
• Y – Matched LACSLink record
• N – LACSLink match NOT found
• F – False-positive LACSLink record
• S – Secondary information (unit number) removed to make
a LACSLink match
• Blank – Not processed through LACSLink
GS-LACSLINK-SHUTDOWN 2
• Y – False-positive occurred and LACSLink library shutdown.
• N – LACSLink library has not shutdown or not loaded.
GS-LACSLINK-RETCODE 3
LACSLink return code.
• A – Matched LACSLink record
• 00 – LACSLink match NOT found
• 09 – Matched to highrise default, but no LACSLink
conversion
• 14 – Found LACSLink match, but no LACSLink conversion
• 92 – Secondary information (unit number) removed to make
a LACSLink match
• Blank – Not processed through LACSLink
GS-LASTLINEc 61
Complete last line (ZIP + 4 not available with GSMGET or
intersection matches).
GS-LASTLINE-SHORT 61
This is the address "lastline". It contains the values of
GS_CITY_SHORT, GS_STATE, and GS_ZIP10.
Whenever possible, this field is 29 characters or less:
• 13-character city name
• 2 (comma and space)
• 2-character state abbreviation
• 2 spaces
• 10-digit ZIP code
GS-LAT 11
Latitude of located point (in millionths of degrees).
GS-LINE1 104
GS-LINE2
GS-LINE3
GS-LINE4
GS-LINE5
GS-LINE6
Used for multiple line entry. GeoStan does not process these
as output.
PMB-DESIGNATOR and PMB-NUMBER are not returned in this
mode.
GS-LOC-CODE 5
Location code. For descriptions of location codes, see the
Status Codes appendix.
GS-LON 12
Longitude of located point (in millionths of degrees).
GS-LORANGE 12 A A
House number at low end of range.
GS-LOT-CODEb 2
• A – Ascending
• D – Descending.
eLot ascending and descending value. Only available for
addresses GeoStan can standardize.
GS-LOT-NUMb 5
4-digit eLOT number. Requires an input address GeoStan can
standardize.
GS-LOTSIZE 11 A,P A,P
Lot size of the parcel expressed in square feet; 0 if none.
GS-MATCH-CODE 5
Match code. For descriptions of match codes, see the Status
Codes appendix.
GS-MATCHED-DB
Index of database for matched record.
GS-MCD-NAME 41 A
Minor Civil Division name from the auxiliary file. Blank if no
auxiliary file match.
GS-MCD-NUMBER 6 A
Minor Civil Division number from the auxiliary file. Blank if no
auxiliary file match.
GS-MEC-LAT 13 A,P A,P
Latitude of Minimum Enclosing Circle expressed with an
implied 6 digits of decimal precision; 0 if none. For example:
34809676 means 34.809676.
GS-METRO-FLAG 2
Indicates if GS-CBSA-NAME
• Y – Contains “Metropolitan Statistical Area”
• N – Is non-blank but does not contain “Metropolitan
Statistical Area”
• Blank – Is blank (the county does not contain a CBSA).
GS-METRO-FLAG2 2 I
GS-METRO-FLAG for the second segment in the intersection.
GS-MM-RESULT-CODE 12
Returns a MapMarker style result code.
GS-NAME 41
Street name
GS-NAME2 41 I I
Second street name in an intersection match.
GS-NAME-CITY 29
City name for the matched address from the City State record.
GS-NAME-SHORT 41
The short street name field contains the short street name used
to construct the short address line.
All attempts are made to abbreviate this name according to the
process specified by the USPS in the 30 Character
Abbreviation - Cycle M Flow Chart. If an abbreviated address
cannot be constructed that is 30 characters or less, this field
then contains the same street name value as the GS_NAME
field variable return.
GS-PARCEN-ELEVATION 7 A,P A,P
Elevation, in feet, of the geocode at the parcel centroid.
GS-PARCEN-ELEVATION-METERS 7 A,P A,P
Elevation, in meters, of the geocode at the parcel centroid.
GS-POSTDIR 3
Postfix direction. Can be blank, N, S, E, W, NE, NW, SW, or
SE.
GS-POSTDIR2 3 I I I
Cross street postfix direction.
GS-POSTDIR-SHORT 3
Postdir from the GS-ADDRLINE-SHORT.
GS-PREDIR 3
Prefix direction. Can be blank, N, S, E, W, NE, NW, SW, or SE.
GS-PREDIR2 3 I I I
Cross street prefix direction.
GS-PREDIR-SHORT 3
Predir from the GS-ADDRLINE-SHORT.
GS-PREF-CITY 29
Preferred city name for the output ZIP Code of the matched
address.
GS-QCITY 10
State , city , or finance numbers.
GS-R-RTE-DFLT 2 A
Match indication for rural routes.
• N – Matched to an exact rural route record.
• Y – Did not find an exact record. Matched to the USPS
default rural route record. Check the input address for
accuracy and completeness.
• Blank – Does not apply to the input address (for example,
street addresses, P.O. Boxes, and General Delivery
addresses) or no match found.
GS-RANGE-PARITY 41 A
Indicates the parity of the house number in the range.
• E – Even
• O – Odd
• B – Both
GS-RDI-RETCODE
USPS Residential Delivery Indicator (requires DPV-confirmed
ZIP+4)
• Y - Address is a residence
• N - Address is a business
• Blank - Address was not presented to RDI or RDI data not
loaded
GS-REC-TYPEb 2 A A
Range record type.
• A – Auxiliary file
• F – Firm
• G – General delivery
• H – Highrise
• P – PO Box
• R – Rural route/highway contract
• S – Street
• T – TIGER file
• U - User Dictionary
GS-RESBUS 2 A,P A,P
Usage indicator
• R – Residential use
• B – Business use
• M – Mixed use – residential and business
• X – Unknown use
GS-ROAD-CLASS 3 A
Road class code.
• 0 – Minor road, main data file
• 1 – Major road, main data file
• 10 – Minor road, supplemental file
• 11 – Major road, supplemental data file
GS-ROAD-CLASS2 3 I
GS-ROAD-CLASS for the second segment in the intersection.
GS-SEG-HIRANGE 12
High house number in segment.
GS-SEG-HIRANGE2 12 I
GS-SEG-HIRANGE for the second segment in the intersection.
GS-SEG-LORANGE 12
Low house number in segment.
GS-SEG-LORANGE2 12 I
GS-SEG-LORANGE for the second segment in the intersection.
GS-SEGMENT-DIRECTION 2
• F – Numbers are forward
• R – Numbers are reversed
GS-SEGMENT-DIRECTION2 2 I
GS-SEGMENT-DIRECTION for the second segment in the
intersection.
GS-SEGMENT-ID 11 A
Segment ID (TLID) or unique ID from premium data vendors.
GS-SEGMENT-ID2 11 I
GS-SEGMENT-ID for the second segment in the intersection.
GS-SEGMENT-PARITY 2
Odd numbers in the segment are on:
• L – Left side of the street
• R – Right side of the street
• B – Both sides of the street
• U – Unknown
GS-SEGMENT-PARITY2 2 I
GS-SEGMENT-PARITY for the second segment in the
intersection.
GS-STATE 3
State abbreviation.
GS-STATE-FIPS 3
State FIPS code.
GS-STREET-SIDE 2 A
The matched address is on the following side of the street:
• L – Left side of the street
• R – Right side of the street
• B – Both sides of the street
• U – Unknown side of the street
This is relative to the segment end points and the segment
direction (GS-SEGMENT-DIRECTION).
NOTE: This enum does not reflect the value in the "Side of
Street" field of any particular data vendor.
GS-SUITELINK-RET-CODE 4 A
• A - SuiteLink record match.
• 00 - No SuiteLink match.
• Blank - This address was not processed through SuiteLink.
GS-TFID 10 A,P A,P
TIGER Face Identifier. This field can be used to match to all
Census geocodes using external data; 0 if none.
GS-ZIP4b 5 A A A
4-digit ZIP Code extension.
GS-ZIP9c 10 A A A
9-digit ZIP Code (ZIP + 4).
GS-ZIP10c 11 A A A
9-digit ZIP Code (ZIP + 4) with dash separator.
GS-ZIP-CARRTSORT 2 A
Indicates the type of cart sort allowed.
• A – Automation cart allowed, optional cart merging allowed.
• B – Automation cart allowed, optional cart merging not
allowed.
• C – Automation cart not allowed, optional cart merging
allowed.
• D – Automation cart not allowed, optional cart merging not
allowed.
GS-ZIP-CITYDELV 2 A
Indicates if city-delivery is available.
• Y – Post office has city-delivery carrier routes
• N – Post office does not have city-delivery
GS-ZIP-CLASS 2
ZIP Classification Code:
• Blank – Standard ZIP Code
• M – Military ZIP Code
• P – ZIP Code has P.O. Boxes only
• U – Unique ZIP Code. (A unique ZIP Code is a ZIP Code
assigned to a company, agency, or entity with sufficient mail
volume to receive its own ZIP Code.)
GS-ZIP-FACILITY 2
Returns USPS City State Name Facility Code.
• A – Airport Mail Facility (AMF)
• B – Branch
• C – Community Post Office (CPO)
• D – Area Distribution Center (ADC)
• E – Sectional Center Facility (SCF)
• F – Delivery Distribution Center (DDC)
• G – General Mail Facility (GMF)
• K – Bulk Mail Center (BMC)
• M – Money Order Unit
• N – Non-Postal Community Name, Former Postal Facility,
or Place Name
• P – Post Office
• S – Station
• U – Urbanization
GS-ZIP-UNIQUE 2
• Y – unique ZIP Code. (ZIP Code assigned to a company,
agency, or entity with sufficient mail volume to receive its
own ZIP Code.)
• Blank – Not applicable.
b Blank if running in CASS mode and you have not initialized DPV or the output address does not DPV confirm.
c Last 4 digits are blank if running in CASS mode and you have not initialized DPV or the output address does not DPV confirm. For GsMultipleGet(), GeoStan returns ZIP+4 but only for Address
matches.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC 9(9) BINARY.
01 GSOPTIONS PIC 9(9) BINARY.
01 OUTLEN PIC 9(9) BINARY.
01 CITY-NAME PIC X(USER LEN).
01 RECNUM PIC S9(9) BINARY.
*
CALL “GSCITYDG” USING GSID, RECNUM, GSOPTIONS, CITY-NAME, OUTLEN,
GSFUNSTAT.
Arguments
GSOPTIONS Symbolic constant for the data item to retrieve. The following table
lists the valid variables. Input.
GS-CITY-CTYSTKEY (7) 6-character USPS City State Key that uniquely identifies a
locale in the city/state file.
GS-CITY-MAILIND (2) • 1 – Can use City State Name as last line on mail piece
• 0 – Cannot use City State Name as last line on main piece
GS-CITY-QCITY (10) City number, using the format ssffffccc, where s is the
state number, f is the Finance number, and c is the city
number
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSCITYFF or GSCITYFN
GSCITYFF
Finds the first city matching partial name or valid ZIP Code.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 STATE-NAME PIC X(USER LEN).
01 CITY-NAME PIC X(USER LEN).
*
CALL “GSCITYFF” USING GSID, STATE-NAME, CITY-NAME, GSFUNSTAT.
Arguments
STATE-NAME Proper state abbreviation for the searched state, or " " for a ZIP Code
search. Input.
CITY-NAME City to search for (may be just a partial string), or a 3-digit or 5-digit
ZIP Code. Input.
Return Values
Record number of the city located, or zero if GeoStan did not find any cities.
Prerequisites
GSCLEAR
Notes
This procedure retrieves the record number of the first city in a state that matches the city or
ZIP Code search string. For example, if the entered state string is CA and the city string is S,
Geostan finds the first city that begins with S in California. If the entered city string is 803
and the state string is null, GeoStan the first city in that sectional center. GeoStan does not
return cities in any predefined order.
Before each find procedure, call GSCLEAR to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
Syntax
01 GSID PIC S9(9) BINARY.
01 LSTATUS PIC S9(9) BINARY.
*
CALL “GSCITYFN” USING GSID, LSTATUS.
Arguments
Return Values
Record number of the city located, or zero if GeoStan did not find any cities.
Prerequisites
GSCITYFF or GSCLEAR
Notes
Call this procedure after GSCITYFF.
Before each find procedure, call GSCLEAR to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
GSCLEAR
Clears the data buffer in the internal data structures.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSCLEAR” USING GSID, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
GSDATGET
Returns data for all address and matched elements from GeoStan.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSOPTIONS PIC 9(9) BINARY.
01 GSSWITCH PIC 9(9) BINARY.
01 OUTPUT-STRING PIC X(USER LEN).
01 OUTLEN PIC 9(4) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSDATGET” USING GSID, GSOPTIONS, GSSWITCH, OUTPUT-STRING,
OUTLEN, GSFUNSTAT.
Arguments
If the input address does not match, setting GSOPTIONS to GS-OUTPUT returns the address
exactly as entered, except for the last line information, which returns only the parsed last
line components.
The parsed last line components correspond to the following variables:
GS-STATE
If there is extra data on the input last line (GS-LASTLINE), this data is not retrievable. For
example, in the last line “BOULDER CO 80301 US OF A”, “US OF A” is not retrievable from
any GSDATGET() procedure.
Note: For valid variables, see “Variables for storing and retrieving data” on page 279.
OUTLEN Maximum length of data for GeoStan to return. The COBOL copy
member “GEOSTAN” lists as constants the recommended buffer
size for each item. These sizes are the maximum lengths required to
get the full output string. You can allocate a buffer that is smaller or
larger than these values. However, if bufLen is shorter than the
returned data, GeoStan truncates the data and does not generate an
error. Input.
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSSFINDWP
Notes
This procedure retrieves data elements from internal GeoStan buffers for either the original
(input) or matched (output) data elements. To retrieve original data, set GSOPTIONS to GS-
INPUT. To retrieve matched data, set GSOPTIONS to GS-OUTPUT.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 GSOPTIONS PIC 9(9) BINARY.
01 VALUE PIC X(LEN).
*
CALL “GSDATSET” USING GSID, GSOPTIONS, VALUE, GSFUNSTAT.
Arguments
GSOPTIONS Symbolic constant for the data item to load. See “Variables for
storing and retrieving data” on page 279” for a list of valid variables.
Input.
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSINITWP
Notes
This procedure loads data elements into internal GeoStan buffers. When loading address
information as a complete address or last line, GeoStan parses the data into fields. For
example, if you entered a last line of “Boulder, CO 80301-1234”, GeoStan parses the data
and sets the city, state, ZIP, and ZIP + 4 fields. You can retrieve parsed data using GSDATGET
and requesting the INPUT to these fields.
If you are passing both an address line and a last line or ZIP Code, be sure to enter the last
line or ZIP Code first to ensure the greatest accuracy in address standardization.
If you are passing both the address information and the last line information as one input
line, enter the address information first.
Using the appropriate parameters defined in the COBOL copy member “GEOSTAN”, you
can pass single line addresses, two-line addresses, or multiline addresses of up to six lines.
For more information, see Appendix B: Extracting Data from GSD Files.
Do not call GSSMM after a call to GSDATSET. If you need to change the match mode in mid-
process, you must re-enter the data for the current address with GSDATSET.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 DB-NUMBER PIC S9(9) BINARY.
01 ITEM-CODE PIC S9(9) BINARY.
01 STRING-BUFFER PIC X(USER LEN).
01 BUFFER-LENGTH PIC S9(9) BINARY.
*
BUFFER-LENGTH = LENGTH OF STRING-BUFFER.
CALL "GSDBMETA" USING GSID, ITEM-CODE, DB-NUMBER, STRING-BUFFER,
BUFFER-LENGTH, GSFUNSTAT.
Arguments
Return Values
Returns.
Prerequisites
GSINITWP
Notes
The value in the string buffer is space-padded to the length of the buffer and has no
terminator. If the buffer length is shorter than the available value, the returned value will be
truncated. The maximum size of any string returned is 255 characters.
GSDPVGCS
Obtains the complete DPV statistics since the application initialized DPV.
Syntax
01 GSID PIC S9(9) BINARY.
01 GS-LACS-COMPLETE-STATS
01 RETURN-CODEPIC 9(9) BINARY.
CALL "GSDPVGCS" USING GSID, GS-DPV-COMPLETE-STATS, GS-DCS-SIZE,
RETURN-CODE.
Arguments
GS-SUCCESS
Prerequisites
GSINITWP
GSDPVGFD
Retrieves the detail record for a DPV false positive report.
Syntax
01 GSID PIC S9(9) BINARY.
01 GS-FALSE-POS-DETAIL-DATA
01 RETURN-CODE PIC 9(9) BINARY.
CALL "GSDPVGFD" USING GSID, GS-FALSE-POS-DEFAILT-DATA, GS-FPDD-SIZE,
RETURN-CODE.
Arguments
Return Values
GS-SUCCESS
Prerequisites
GSDPVINR
GSDPVGFH
Retrieves DPV statistics for the header record for a DPV false positive report.
Syntax
01 GSID PIC S9(9) BINARY.
GS-FALSE-POS-HEADER-DATA
01 RETURN-CODE PIC 9(9) BINARY.
CALL "GSDPVGFH" USING GSID, GS-FALSE-POS-HEADER-DATA, GS-FPHD-SIZE,
RETURN-CODE.
Arguments
Return Values
GS-SUCCESS
Prerequisites
GSINITWP with the appropriate DPV initialization properties set.
GSERRGET
Retrieves current error information.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 MESSAGE-STRING PIC X(256).
01 DETAIL-STRING PIC X(256).
*
CALL “GSERRGET” USING GSID, MESSAGE-STRING, DETAIL-STRING, GSFUNSTAT.
Arguments
MESSAGE-STRING Basic explanation for the error; up to 256 bytes in length. Output.
Return Values
Error number of the most recent GeoStan error.
-1 No error.
Alternates
GSERRGTX
GSERRGTX
Retrieves informational, error, and fatal warning messages for the current thread.
Syntax
01 GSID PIC S9(9) BINARY.
01 ERROR-MESSAGE PIC X(256).
01 DETAILS PIC X(256).
01 GSFUNSTAT PIC S9(9) BINARY.
Arguments
DETAILS Descriptive message, such as the file name associated with the error.
Output.
Prerequisites
GSINITWP and GSERRHAS
GSERRHAS
Indicates if any errors occurred or any information messages are available in the current
thread.
Syntax
01 GSID PIC S9(9) BINARY.
01 MOREERRORS PIC S9(9) BINARY.
Arguments
MOREERRORS Zero if there are no more error messages to retrieve (via GSERRGTX),
and non-zero if there are additional messages. Output.
Return Values
Prerequisites
GSINITWP
GSFCASSH
Writes a CASS 3553 report to the header buffer argument.
Syntax
01 GSID PIC S9(9).
01 GSEXTENDCASSDATA
01 HEADER-BUFFER PIC X(USER LEN).
01 DATA-SIZE PIC S9(9) BINARY.
01 BUFSIZE PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
Arguments
GSEXTENDCASSDATA Pointer to the CASSS report data structure. The following table
contains information about the structure. Input.
05 GS-ECD-STRUC-TVERSION PIC S9(9) BINARY.
HEADER-BUFFER Buffer containing the CASS header line from the Stage file. Input,
Output.
Return Values
GS-SUCCESS
GS-ERROR
GS-WARNING
Prerequisites
GSINITWP
Notes
When you specify a version number for either version, GS-ECD-LOT-VERSION or GS-ECD-LOT-
VERSION, GeoStan updates the corresponding fields in the header buffer similar to GSWECASS.
For example, entering a version number for GS-ECD-LOT-VERSION prompts GeoStan to fill the
following fields in CASS355.frm:
• Section “B. List”, Item “2b”: Data List Processed Z4Change
• Section “B. List”, Item “3b”: Data of Database Product used Z4Change.
• Section “C. Output”, Item “1b”: Total coded Z4Change Processed.
To develop CASS certified application in GeoStan, you must have the correct license
agreement with Pitney Bowes. You must also obtain CASS certification from the USPS for
your application. Using GeoStan does not make an application CASS certified. For
information on becoming CASS certified, see Appendix E: CASS certification overview.
GSFDFPD
Formats a DPV false positive detail record from GSDPVGFD.
Arguments
HEADER Buffer containing the DPV false positive detail record after GSFDPD
successfully completes. When the application writes the false
positive report, it writes this buffer to the last line of the file. Output.
Return Values
GS-SUCCESS
Prerequisites
GSDPVGFD
GSFDFPH
Formats a DPV false positive header record with data from GSDPVGFD.
Syntax
01 GSID PIC S9(9) BINARY.
01 GS-FALSE-POS-HEADER-DATA
01 RETURN-CODE PIC 9(9) BINARY.
01 HEADER PIC X(len).
01 HEADER-SIZE PIC 9(9) BINARY VALUE len.
HEADER Buffer containing the DPV false positive header after GSFDFPH
successfully completes. When the application writes the false
positive report, it writes this buffer to the first line of the file. Output.
Return Values
GS-SUCCESS
Prerequisites
GSDPVINR
GSDPVGFH
Syntax
01 GSID PIC S9(9) BINARY.
01 RANGE-HANDLE PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSFFRANG” USING GSID, RANGE-HANDLE, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS Found a match. You can retrieve the data for that match using
GSHGET.
Prerequisites
GSINITWP and GSCLEAR
Notes
You must call GSFFSEG before calling GSFFRANG.
GSFFSEG
Finds the first segment object that meets the search criteria.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 SEGMENT-HANDLE PIC S9(9) BINARY.
*
CALL “GSFFSEG” USING GSID, SEGMENT-HANDLE, GSFUNSTAT.
Arguments
Return Values
GSGS-SUCCESS Found a match. You can retrieve the data for that match using
GSHGET.
Prerequisites
GSINITWP and GSCLEAR
Notes
This procedure finds the first street in the current search area that meets the name criteria,
and also sets the area and criteria for subsequent segment and range searches.
If you are using GSFFSEG to find a street that has a number as a component of the street
name, such as “US HWY 41,” or “I-95,” enter just the number; the text is not part of the
index for such streets.
GSFFSEG and GSFNRANG procedures work together to allow you to access to the entire
address directory database.
See Appendix B: Extracting Data from GSD Files for more information on the Find First and
Find Next procedures.
GSFFST
Finds the first street object that meets the search criteria.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 STREET-HANDLE PIC S9(9) BINARY.
01 GSOPTIONS PIC 9(9) BINARY.
01 LOCALE PIC X(USER LEN).
01 STREET-NAME PIC X(USER LEN).
01 STREET-NUMBER PIC X(USER LEN).
*
CALL “GSFFST” USING GSID, STREET-HANDLE, GSOPTIONS, LOCALE, STREET-
NAME, STREET-NUMBER, GSFUNSTAT.
Arguments
GSOPTIONS Set the type of search performed by GeoStan. The following table
contains the types of searches available. Input.
GS-ZIP-SEARCH Required. GeoStan searches the ZIP Code specified by LOCALE.
GS-CITY- Required. GeoStan searches the city and state specified by LOCALE.
SEARCH
STREET-NAME Street name, or partial street name, for which to search. If GSOPTIONS
is set to GS-SDX-SEARCH, the STREET-NAME is a pointer to a numeric
soundex key. Input.
Limits the search to street names that begin with the name string. If STREET-NAME is set to
“APPLE,” then only streets beginning with Apple are returned, such as Apple or Appleton. If
STREET-NAME is not specified, GeoStan finds all the streets specified by LOCALE.
Return Values
GSGS-SUCCESS Found a match. You can retrieve the data for that match using
GSHGET.
Prerequisites
GSINITWP and GSCLEAR
Notes
You must call GSFFST before GSFFSEG. This procedure also sets the area and criteria for
subsequent segment and range searches.
If you are using GSFFST to find a street that has a number as a component of the street
name, such as “US HWY 41” or “I-95,” enter just the number; the text is not part of the index
for such streets.
See Appendix B: Extracting Data from GSD Files for more information on the Find First and
Find Next procedures.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC 9(9) BINARY.
01 OUTLEN PIC 9(9) BINARY.
01 STATE-FOUND PIC X(USER LEN).
01 STATE-PATTERN PIC X(USER LEN).
*
CALL “GSFFSTAT” USING GSID, STATE-PATTERN, STATE-FOUND, OUTLEN,
GSFUNSTAT.
Arguments
Return Value
GS-ERROR
GS-SUCCESS
GS-NOT-FOUND
Prerequisites
GSINITWP or GSCLEAR
Notes
This procedure returns the proper abbreviation for the requested state. You can request
states either by ZIP Code, full state name, or an alternate abbreviation.
Before each find procedure, call GSCLEAR to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
MOVE SPACES TO GS-GEOGRAPHIC-INFO.
MOVE <a City Name> TO GS-INPUT-CITY.
MOVE <a County Name> TO GS-INPUT-COUNTY.
MOVE <a State Name/Abbreviation> TO GS-INPUT-STATE.
Arguments
GS-INPU-STATE Proper state abbreviation or name for the searched state. Input.
Return Values
First Geographic Information Record which has a partial match to the input.
"GSFUNSTAT" contains a value of "GS-SUCCESS" if there are one or more matching records.
The following named items are defined in module the COBOL copy member "GEOSTAN"
for this function:
GS-OUTPUT-LAT Latitude.
GS-OUTPUT-LONG Longitude.
Notes
This procedure retrieves the first Geographic information record which matches the input
city, county, or state names. The match logic may qualify more than one response. Use
calls to "GSFGN" to retrieve the additional responses.
The COBOL copy member "GEOSTAN" includes the record "GS-GEOGRAPHIC-INFO" which
has the correct format for this function.
Input values may be zero-byte terminated strings or fixed-length with space padding. The
returned values are fixed-length with space padding. The optional field "GS-INPUT-COUNTY"
should be filled with spaces if it is not used.
GSFGFX
Finds the first city, county, and or state centroid match from the set of possible matches
found.
Syntax
01 GS-GEOGRAPHIC-INFO-EX.
05 GS-INPUT-CITY PIC X(39).
05 GS-INPUT-COUNTY PIC X(39).
05 GS-INPUT-STATE PIC X(20).
05 GS-OUTPUT-CITY PIC X(39).
05 GS-OUTPUT-COUNTY PIC X(39).
05 GS-OUTPUT-STATE PIC X(20).
05 GS-OUTPUT-LAT PIC X(11).
05 GS-OUTPUT-LONG PIC X(12).
05 GS-OUTPUT-RANK PIC X(2).
05 GS-OUTPUT-RESULT-CODE PIC X(11).
05 GS-OUTPUT-LOCATION-CODE PIC X(5).
05 GS-CLOSE-MATCH-FLAG PIC X.
05 GS-INPUT-GEO-LIB-VER-EX PIC 9(9) BINARY.
05 GS-OUTPUT-FIPS-CODE PIC X(6).
*
CALL "GSFGFX" USING NAME,.
Arguments
GS-INPUT-STATE Proper state abbreviation or name for the searched state. Input.
GS-OUTPUT-RANK Returned geographic rank of the city for city centroid. Output.
Return Values
GS-SUCCESS
GS-ERROR
GS-NOT-FOUND
Prerequisites
GSINITWP
Notes
It is recommended that the user first use the Last-line lookup functions to standardize the
city, county and state names. This function only performs minimal fuzzy matching on the
input city and county names. The location code returned by this function is to provide users
with a location code equivalent and is not retrievable using GsDataGet. It is merely provided
to offer a consistent label for the type of address match that is returned and will only consist
of one of the three Geographic location codes (GM – City, GC – County and GS – State).
Example
Use the following parameter area defined in the COBOL copy member named GEOSTAN
filling in the fields with names beginning with GS-INPUT.
01 GS-GEOGRAPHIC-INFO-EX.
05 GS-INPUT-CITY PIC X(39).
05 GS-INPUT-COUNTY PIC X(39).
05 GS-INPUT-STATE PIC X(20).
05 GS-OUTPUT-CITY PIC X(39).
05 GS-OUTPUT-COUNTY PIC X(39).
05 GS-OUTPUT-STATE PIC X(20).
05 GS-OUTPUT-LAT PIC X(11).
05 GS-OUTPUT-LONG PIC X(12).
05 GS-OUTPUT-RANK PIC X(2).
05 GS-OUTPUT-RESULT-CODE PIC X(11).
For a COBOL coding example, see the example for GSFGF. The call is the same except that
there are more output fields returned with GSFGFX.Finds the first geographic information
record with partial matching to input names.
GSFGN
Finds the next geographic information record with partial matching to input names.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL "GSFGN" USING GSID, GS-GEOGRAPHIC-INFO, GSFUNSTAT.
Arguments
Return Values
Next Geographic Information Record which has a partial match to the input.
"GSFUNSTAT" contains a value of "GS-SUCCESS" if there are one or more matching records.
See GSFGF for the remainder of the output fields.
Prerequisites
GSINITWP
GSFGF (Previous call with return status equal "GS-SUCCESS")
Notes
This procedure retrieves the next Geographic information record which matches the input
city, county, or state names. A previous call to "GSFGF" is required, with a returned status of
"GS-SUCCESS".
The COBOL copy member "GEOSTAN" includes the record "GS-GEOGRAPHIC-INFO" which
has the correct format for this function.
Input values may be zero-byte terminated strings or fixed-length with space padding. The
returned values are fixed-length with space padding. The optional field "GS-INPUT-COUNTY"
should be filled with spaces if it is not used.
Syntax
01 GS-GEOGRAPHIC-INFO-EX.
05 GS-INPUT-CITY PIC X(39).
05 GS-INPUT-COUNTY PIC X(39).
05 GS-INPUT-STATE PIC X(20).
05 GS-OUTPUT-CITY PIC X(39).
05 GS-OUTPUT-COUNTY PIC X(39).
05 GS-OUTPUT-STATE PIC X(20).
05 GS-OUTPUT-LAT PIC X(11).
05 GS-OUTPUT-LONG PIC X(12).
05 GS-OUTPUT-RANK PIC X(2).
05 GS-OUTPUT-RESULT-CODE PIC X(11).
05 GS-OUTPUT-LOCATION-CODE PIC X(5).
05 GS-CLOSE-MATCH-FLAG PIC X.
05 GS-INPUT-GEO-LIB-VER-EX PIC 9(9) BINARY.
05 GS-OUTPUT-FIPS-CODE PIC X(6).
*
CALL "GSFGFX" USING NAME,.
Arguments
GS-INPUT-STATE Proper state abbreviation or name for the searched state. Input.
GS-OUTPUT-RANK Returned geographic rank of the city for city centroid. Output.
Return Values
GS-SUCCESS
GS-ERROR
GS-NOT-FOUND
Prerequisites
GSINITWP
Notes
It is recommended that the user first use the Last-line lookup functions to standardize the
city, county and state names. This function only performs minimal fuzzy matching on the
input city and county names. The location code returned by this function is to provide users
with a location code equivalent and is not retrievable using GsDataGet. It is merely provided
to offer a consistent label for the type of address match that is returned and will only consist
of one of the three Geographic location codes (GM – City, GC – County and GS – State).
Example
Use the following parameter area defined in the COBOL copy member named GEOSTAN
filling in the fields with names beginning with GS-INPUT.
01 GS-GEOGRAPHIC-INFO-EX.
05 GS-INPUT-CITY PIC X(39).
05 GS-INPUT-COUNTY PIC X(39).
05 GS-INPUT-STATE PIC X(20).
05 GS-OUTPUT-CITY PIC X(39).
05 GS-OUTPUT-COUNTY PIC X(39).
05 GS-OUTPUT-STATE PIC X(20).
05 GS-OUTPUT-LAT PIC X(11).
05 GS-OUTPUT-LONG PIC X(12).
05 GS-OUTPUT-RANK PIC X(2).
05 GS-OUTPUT-RESULT-CODE PIC X(11).
05 GS-OUTPUT-LOCATION-CODE PIC X(5).
05 GS-CLOSE-MATCH-FLAG PIC X.
05 GS-INPUT-GEO-LIB-VER-EX PIC 9(9) BINARY.
05 GS-OUTPUT-FIPS-CODE PIC X(6).
For a COBOL coding example, see the example for GSFGF.The call is the same except that
there are more output fields returned with GSFGFX. Finds the first geographic information
record with partial matching to input names.
GSGETNDB
Returns the number of loaded databases.
Syntax
01 GSID PIC S9(9) BINARY.
01 DBCOUNT PIC S9(9) BINARY.
Arguments
Return Values
Count of GeoStan database files loaded, or zero if GeoStan did not load any databases.
Prerequisites
GSINITWP
Syntax
01 GSID PIC S9(9) BINARY.
01 PROPLIST PIC 9(9) BINARY.
01 GSFUNSTAT PIC 9(9) BINARY.
*
CALL “GSFINDWP” USING GSID, FIND-PROP-LIST, GSFUNSTAT.
Arguments
Category Description
AnyForward Find properties that are usable with any use of GSFINDWP
which is doing "forward geocoding", that is, standardizing
and geocoding an input address.
GeoStanReverse Find properties that are usable with any use of GSFINDWP
which is doing a reverse geocoding search.
GeoStanAPN Find properties that are usable with any use of GSFINDWP
which is doing an APN search.
GeoStanFindFirstStreet Find properties that are usable with any use of GSFINDWP
which is doing an FindFirstStreet/Segment/Range search.
Custom Find properties that are usable with any use of GSFINDWP
which is using custom find properties.
The properties with the categories listed below in the Category column cannot be used with
the properties with categories listed in the Conflicting Category column.
Any None.
AnyForward GeoStanReverse
GeoStanAPN
GeoStanFindFirstStreet
GeoStanReverse GeoStanAPN
GeoStanFindFirstStreet
Custom
AnyForward
GeoStanAPN GeoStanFindFirstStreet
Custom
AnyForward
GeoStanReverse
GeoStanFindFirstStreet Custom
AnyForward
GeoStanReverse
GeoStanAPN
Custom GeoStanReverse
GeoStanAPN
GeoStanFindFirstStreet
GeoStan does not allow an application to add a property from the category listed in the
Category column, if the property list already contains a Match Mode property type listed in
the MatchMode value column below:
Custom Relax
Interactive
Close
Exact
GeoStanReverse Custom
GeoStanAPN
GeoStanFindFirstStreet
GS-FIND-ADDRCODE Attempts to standardize and find an address geocode. Set this switch if
you want the address parsed and standardized. If this switch is not set,
GeoStan uses only the input ZIP and ZIP + 4 address elements. Default
= False.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
• Match modes: Relax, Interactive, Close, Exact, Custom, and CASS
GS-FIND-ALTERNATE-LOOKUP Determines whether the preferred lookup is to look for the streets first or
the firms first. Default = 3.
• 1 - GS-PREFER-STREET-LOOKUP - Matches to the address line, if
a match is not made, then GeoStan matches to the Firm name line.
• 2 - GS-PREFER-FIRM-LOOKUP - Matches to the Firm name line, if
a match is not made, then GeoStan matches to address line.
• 3 - GS-STREET-LOOKUP-ONLY (default) - Matches to the address
line.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
• Match modes: Relax, Interactive, Close, Exact, and Custom.
GS-FIND-APN-SEARCH Specifies that GeoStan match an input FIPS and APN code to receive
information on the corresponding parcel. Default = False.
• Category: GeoStanAPN
• Compatible with: GeoStanAPN and Any.
• Conflicts with: GeoStanFindFirstStreet, AnyForward, and
GeoStanReverse.
• Match modes: Relax, Interactive, Close, and CASS.
GS-FIND-APPROXIMATE-PBKEY When using the Master Location Dataset (MLD), when a match is not
made to an MLD record, this feature returns the GS-PB-KEY of the
nearest MLD point location. Default = False.
The search radius for the nearest MLD point location can be configured
to 0-5280 feet. The default is 150 feet.
This type of match returns a GS-PB-KEY with a leading ‘X’ rather than a
‘P’, for example, X00001XSF1IF.
The GS-INIT-OPTIONS-SPATIAL-QUERY init property must be set to
True to enable this feature.
For more information, see “PreciselyID Fallback” on page 70.
• Category: AnyForward, GeoStanReverse
• Compatible with: AnyForward, Any, Custom, GeoStanReverse,
GeoStanAPN, and GeoStanFindFirstStreet.
• Conflicts with: None.
• Match modes: Relax, Interactive, Close, Exact, and CASS.
GS-FIND-BUILDING-SEARCH Controls the ability to search by building name entered in the address
line. Enables matching to building names even when no unit numbers
are present. Default = False.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
• Match modes: Relax, Interactive, Close, Exact, and Custom.
GS-FIND-CENTERLINE-OFFSET Offset distance from the street center for a centerline match. Values =
Any positive integer, which represents number of feet. Default = 0 feet.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
• Match modes: Exact, Close, CASS, Relax, Interactive and Custom.
GS-FIND-CLOSEST-POINT For reverse geocoding, enables matching to the nearest point address
within the search radius, rather than to the closest feature (e.g. street
segment or intersection as well as point addresses). Default = False.
NOTE: Requires that at least one streets data set and one points data
set are loaded; otherwise, the match will be made to the closest
feature.
• Category: GeoStanReverse
• Compatible with: Reverse and Any.
• Conflicts with: GeoStanAPN, GeoStanFindFirstStreet, Custom,
AnyForward
• Match modes: Match mode has no impact on reverse geocoding.
GS-FIND-CORNER-OFFSET Distance, in feet, to offset address-level geocodes from the street end
points. If the corner offset distance is more than half the segment length,
GeoStan sets the distance to the midpoint of the segment. Default = 50
feet.
• Category: Any
• Compatible with: AnyForward, Any, Custom, GeoStanReverse,
GeoStanAPN, and GeoStanFindFirstStreet.
• Conflicts with: None.
• Match modes: Relax, Interactive, Close, Exact, Custom, and CASS.
GS-FIND-EXPAND-SEARCH- Distance, in feet, to use for the expanded search radius. Default =
RADIUS 132000.
• Category: Any
• Compatible with: AnyForward, Any, Custom, GeoStanReverse,
GeoStanAPN, and GeoStanFindFirstStreet.
• Conflicts with: None.
• Match modes: Relax, Interactive, Close, Exact, and Custom.
GS-FIND-EXPND-SRCH-LIM-TO- Do not cross state boundaries when doing an expanded search. Default
STA = True.
• Category: Any
• Compatible with: AnyForward, Any, Custom, GeoStanReverse,
GeoStanAPN, and GeoStanFindFirstStreet.
• Conflicts with: None.
• Match modes: Relax, Interactive, Close, Exact, and Custom.
GS-FIND-FIRST-LETTER- Enables extra processing for bad first letter (missing, wrong, etc.).
EXPANDED Default = False.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
• Match modes: Relax, Interactive, Close, Custom, and CASS. Ignored
in Exact mode.
NOTE: Custom match mode and the Must Match settings are not
supported in single-line address matching.
NOTE: Custom match mode and the Must Match settings are not
supported in single-line address matching.
NOTE: Custom match mode and the Must Match settings are not
supported in single-line address matching.
NOTE: Custom match mode and the Must Match settings are not
supported in single-line address matching.
NOTE: Custom match mode and the Must Match settings are not
supported in single-line address matching.
GS-FIND-NEAREST-UNRANGED Specifies that GeoStan can match a street segment with no number
ranges. Enabled with GS-FIND-NEAREST-ADDRESS. Ignored for point
data and intersection matches. Default = False.
• Category: GeoStanReverse
• Compatible with: Reverse and Any.
• Conflicts with: GeoStanAPN, GeoStanFindFirstStreet, Custom,
AnyForward
• Match modes: Reverse geocoding doesn’t use match modes - valid
for all match modes.
GS-FIND-PREFER-POBOX Sets the preference to P.O. Box addresses instead of street addresses
for multi-line input addresses. See “Specifying a preference for street
name or P.O. Box” on page 36 for more information. Ignored if
processing in CASS mode. Default = False.
If both GS-FIND-PREFER-POBOX and GS-FIND-PREFER-STREET
are set to True, then they are ignored and the default, GS-FIND-
PREFER-STREET is used.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
• Match modes: Relax, Interactive, Close, Exact, and Custom.
GS-FIND-PREFER-STREET Sets the preference to street addresses instead of P.O. Box addresses
for multi-line input addresses. Ignored if processing in CASS mode.
Default = False.
If both GS-FIND-PREFER-POBOX and GS-FIND-PREFERSTREET are
set to True, then they are ignored and the default, GS-FIND-PREFER-
STREET is used.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN,
GeoStanFindFirstStreet and Custom.
• Match modes: Relax, Interactive, Close, Exact, and Custom.
GS-FIND-PREFER-ZIP-OVER- Prefer candidates matching input ZIP over matches to input city. Default
CITY = False.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
• Match modes: Relax, Close, Exact, and Custom. Ignored for
Interactive and CASS match modes. Interactive match mode returns
the best address regardless of this setting.
GS-FIND-SEARCH-AREA Assists in finding a match when the input address contains limited or
inaccurate city or ZIP Code information. Default = 0.
0 - GS-FIND-SEARCH-AREA-CITY - Searches the specified city.
1 - GS-FIND-SEARCH-AREA-FINANCE - Searches the entire Finance
Area for possible streets.
This option has no effect when performing a ZIP centroid match.
2 - GS-FIND-SEARCH-AREA-EXPANDED - This value effectively has
two options that can be set:
Allows the setting of the radius in miles (up to 99) around which your
record lies. The default radius setting is 25 miles.
Allows for limiting the search to the state. The default setting is True.
• Category: Any
• Compatible with: Any, AnyForward, GeoStanReverse, GeoStanAPN,
and GeoStanFindFirstStreet.
• Conflicts with: None.
• Match modes: Relax, Interactive, Close, Exact, and Custom. Search
area cannot be changed in CASS match mode.
GS-FIND-SEARCH-DIST Radius, in feet, that GeoStan searches for a reverse geocode match.
The range is 0 - 5280 feet. Default = 150 feet.
GS-FIND-SEARCH-DIST is also used for the Predictive Lastline and
PreciselyID Fallback features in forward geocoding.
• Category: GeoStanReverse
• Compatible with: GeoStanReverse and Any.
• Conflicts with: GeoStanAPN, GeoStanFindFirstStreet, and
AnyForward (see the note above for the exceptions for use in forward
geocoding).
• Match modes: Relax, Interactive, Close, Exact, Custom, and CASS.
GS-FIND-STREET-OFFSET Left and right offset distance from the street segments. The range is 0 -
999 feet. Default = 50 feet.
• Category: Any
• Compatible with: AnyForward, Any, Custom, GeoStanReverse,
GeoStanAPN, and GeoStanFindFirstStreet..
• Conflicts with: None.
• Match modes: Relax, Interactive, Close, Exact, Custom, and CASS.
GS-FIND-WIDE-SEARCH Considers all records matching the first letter of the street name, rather
than the soundex key on the street name, which allows a wider search.
Default = False.
This option has no effect when performing a ZIP centroid match.
• Category: Any
• Compatible with: AnyForward, Any, Custom, GeoStanReverse,
GeoStanAPN, and GeoStanFindFirstStreet.
• Conflicts with: none.
• Match modes: Relax, Interactive, Close, and Exact.
GS-FIND-Z5-CODE Attempts to find a ZIP centroid match (no ZIP + 4 or ZIP+2). Default =
False.
Not valid when using the reverse geocoding options.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
• Match modes: Relax, Interactive, Close, Exact, Custom, and CASS.
GS-FIND-Z7-CODE Attempts to find a ZIP+2 centroid match only (no ZIP + 4 or ZIP). Default
= False.
Not valid when using the reverse geocoding options.
• Category: AnyForward
• Compatible with: AnyForward and Any.
• Conflicts with: GeoStanReverse, GeoStanAPN, and
GeoStanFindFirstStreet.
• Match modes: Relax, Interactive, Close, Exact, Custom, and CASS.
Return Value
GS-ERROR
GS-SUCCESS
Prerequisites
Notes
The application owns the property list, but GeoStan is the active user.
Do not destroy the property list by calling GSPLSTDE while GeoStan is still using that
property list.
GSFNRANG
Finds the next range object that meets the search criteria.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 RANGE-HANDLE PIC S9(9) BINARY.
*
CALL “GSFNRANG” USING GSID, RANGE-HANDLE, GSFUNSTAT.
Arguments
Return Values
Prerequisites
GSFFSEG and GSCLEAR
Notes
This procedure continues to find objects that match the criteria specified in GSFFRANG.
If GeoStan finds a matching segment, you can retrieve the data for that segment using
GSHGET.
Before each find procedure, call GSCLEAR to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
See Appendix B: Extracting Data from GSD Files for more information on the Find First and
Find Next procedures.
GSFNSEG
Finds the next segment that meets the search criteria.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 SEGMENT-HANDLE PIC S9(9) BINARY.
*
CALL “GSFNSEG” USING GSID, SEGMENT-HANDLE, GSFUNSTAT.
Arguments
Return Values
Prerequisites
GSFFSEG and GSCLEAR
Notes
This procedure continues to find objects that match the criteria specified in GSFFSETG.
If GeoStan finds a matching segment, you can retrieve the data for that segment using
GSHGET.
Before each find procedure, call GSCLEAR to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
See Appendix B: Extracting Data from GSD Files for more information on the Find First and
Find Next procedures.
GSFNST
Finds the next street that meets the search criteria.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 STREET-HANDLE PIC S9(9) BINARY.
*
CALL “GSFNST” USING GSID, STREET-HANDLE, GSFUNSTAT.
Arguments
Return Values
Prerequisites
GSFFST and GSCLEAR
Before each find procedure, call GSCLEAR to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
See Appendix B: Extracting Data from GSD Files for more information on the Find First and
Find Next procedures.
GSFSTAT
Returns if the file successfully opened, and the date of the USPS data used in generating
the primary GSD file.
Syntax
01 GSID PIC S9(9) BINARY.
01 STATE-CODE PIC X(2).
01 GSFUNSTAT PIC 9(4) BINARY.
01 BUILD-DATE PIC 9(4) COMP-5.
*
CALL “GSFSTAT” USING GSID, STATE-CODE, BUILD-DATE, GSFUNSTAT.
Arguments
BUILD-DATE Publish date of the USPS data used in the current GeoStan release.
Output.
Return Values
Series of bit-flags. The following GS-VARIABLEs are used to test these flags:
a eLOT data requires an additional license. However, the Z4Change data is always enabled.
b You must have an additional license to use this file.
Prerequisites
GSINITWP
Example
The following is an example of how to obtain the month/day/year from the build date:
01 GSID PIC S9(9) BINARY.
01 STATE-CODE PIC X(2).
01 GSFUNSTAT PIC S9(4) BINARY.
01 BUILD-DATE PIC 9(4) COMP-5.
8 Add 1 to BUILD-MONTH.
– or –
Syntax
01 GSID PIC S9(9) BINARY.
01 OPTION PIC S9(9) BINARY.
01 GSFUNSTAT PIC 9(9) BINARY.
01 OUTLEN PIC 9(9) BINARY.
01 OUTPUT-STRING PIC X(USER LEN).
*
CALL “GSFSTATX” USING GSID, OPTION, OUTPUT-STRING, OUTLEN, GSFUNSTAT.
Arguments
GS-STATUS-DATUM-STR The NAD used natively by the data. It does not reflect the datum
currently in use by GeoStan. See GSGDATUM and GSSDATUM for
further information on setting the returned NAD.
GS-STATUS-FILE-CHKSUM-NUM Calculated value (an integer) used to check data integrity. The
OUTPUT-STRING and OUTLEN parameters are unused. Set
OUTLEN to 0.
OUTLEN Maximum size of data that GeoStan returns. If OUTLEN is shorter than
the data returned by GeoStan, GeoStan truncates the data and does
not generate an error. Input.
0 USPS
1 TIGER
3 Sanborn point-level
4 Deprecated
8 Centruspoint-level data
9 Auxiliary file
10 User Dictionary
The following table shows the return values for the GS-STATUS-DATUM-STR mode.
0 NAD27
Prerequisites
GSINITWP
GSGCRDX
Retrieves coordinates for the street segment found via GSSFIND.
Syntax
01 GSIDPIC S9(9) BINARY.
01 GSFUNSTATPIC 9(4) BINARY.
01 COORDSOCCURS 64 TIMES.
05 COORD-XPIC S9(9) BINARY.
05 COORD-YPIC S9(9) BINARY.
01 MAXPOINTSPIC 9(4) BINARY.
*
CALL “GSGCRDX” USING GSID, COORDS, MAXPOINTS, GSFUNSTAT.
Return Values
Number of points assigned to buffer.
Prerequisites
GSSFIND
Notes
This procedure returns an array of coordinates for the current feature found via GSSFIND.
The maximum number that GeoStan can return is 64 coordinate pairs, each pair consisting
of two long integers.
GeoStan scales coordinate pairs to integers with four decimal digits of precision. Thus,
GeoStan returns a point at (-98.3, 29.7) as (983000, 297000). This is a different scale from
that expected by Spatial+ and similar GIS applications, which typically express coordinates
in millionths of degrees. You may need to scale coordinates obtained with this procedure
before using them as input to other software libraries or applications.
GSGLIBV
Returns the current version of the GeoStan library.
Syntax
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSGLIBV” USING GSFUNSTAT.
Arguments
Return values
Low Byte = Major version number.
High Byte = Minor version number.
Prerequisites
GSINITWP
Example
The best way to extract the high and low bytes is to subdefine GSFUNSTAT as follows:
01 GSFUNSTAT PIC S9(9) BINARY.
01 GS-MINOR-VERSION PIC 9(2) BINARY.
01 GS-MAJOR-VERSION PIC 9(2) BINARY.
GSHGCRDX
Retrieves the coordinates for a street segment object found via GSFFSEG and
GSFNRANG.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 SEGMENT-HANDLEPIC S9(9) BINARY.
01 MAXPOINTS PIC 9(4) BINARY.
01 COORDS OCCURS <nnn> TIMES.
05 COORD-X PIC S9(9) BINARY.
05 CORRD-Y PIC S9(9) BINARY.
*
CALL “GSHGCRDX” USING GSID, SEGMENT-HANDLE, COORDS, MAXPOINTS,
GSFUNSTAT.
Arguments
SEGMENT-HANDLE Handle of the segment object for the returned coordinates. Input.
Return Values
Number of points assigned to the buffer.
Notes
This procedure returns an array of coordinates for the segment identified in SEGMENT-HANDLE.
GSHGET
Retrieves data for objects found via GSSFFSG and GSFNRANG.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 RANGE-HANDLE PIC S9(9) BINARY.
01 GSOPTIONS PIC 9(9) BINARY.
01 OUTPUT-STRING PIC X(USER LEN)
01 OUTLEN PIC S9(4) BINARY.
Arguments
OUTLEN Maximum size of the data that GeoStan returns. If OUTLEN is shorter
than the data returned by GeoStan, GeoStan truncates the data and
does not generate an error. Input.
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSFFSEG or GSFNRANG
Notes
This procedure retrieves data from the geocode buffer for a given range handle. If you have
a street or segment handle, you must convert the handle to a range handle before you can
use this procedure.
Syntax
01 INIT-PROP-LIST Defined in GEOSTAN copy member.
01 STATUS-PROP-LIST Defined in GEOSTAN copy member.
01 GSID PIC S9(9) BINARY.
CALL 'GSINITWP' USING INIT-PROP-LIST,STATUS-PROP-LIST, GS-ID.
IF GS-ID EQUAL ZERO DISPLAY '** ERROR ** GEOSTAN FAILED TO INITIALIZE’
PERFORM GET-ERROR-MSG
Arguments
GS-INIT-DPV-DATA-ACCESS Indicates the type of files to load and how to access the files. The
following contains the possible values.
• DPV-DATA-FULL-FILEIO - Files are not loaded into memory.
Table access is through file I/O.
• DPV-DATA-FULL-MEMORY - Files are loaded into memory.
Use this option to gain performance improvement by reducing
repetitive file I/O.
• DPV-DATA-SPLIT-FILEIO - Use if your file is sorted by ZIP
Code and you have limited memory. Uses a split data format
that separates the DPV data file into multiple smaller files,
based on the first 2 digits of the ZIP Code. If you sort your
mailing file by ZIP Code, you can use this value to bring the
relevant portion of the DPV file into memory. This process
uses 32 MB of storage, but reduces the number of I/O
requests that normally occurs when you use the full DPV data
file.
• DPV-DATA-FLAT-FILEIO - DPV flat file accessed via file I/O.
GS-INIT-OPTIONS-ZIP-PBKEYS Open the file needed to return PreciselyIDs for ZIP centroid
locations in Master Location Data. If the ZIP centroid file
(zipsmld.gsd) that contains PreciselyIDs loaded successfully,
GS-STATUS-FILE-ZIP-PBKEYS is True. (Default value =
False).
When an address point is not available for an address in Master
Location Data, this option returns a ZIP centroid and the
PreciselyID unique identifier, which can be used to unlock
additional information about an address using GeoEnrichment
data.
To enable returning PreciselyIDs for ZIP centroid locations in
MLD, the GS-FIND-Z-CODE GSFINDWP property needs to be
enabled. If it is not enabled, an "E" location code is returned and
the results data will not include a geocode nor PreciselyID.
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR and GSPSET*
Notes
Initializes GeoStan using a property list. Upon return, this function utilized the properties,
but left the property list intact. The application owns the property lists. The status property
list is guaranteed to contain properties for all defined status properties with their values
properly set.
GSINITWP can be used to initialize GeoStan, DPV, and LACSLink with a single call (if the
appropriate initialization properties are in the init list). When this function successfully
completes, it populates the GS-INIT-GEOSTAN-ID property in the property list referred to by
the pInitProps parameter with the actual GeoStan ID.
If you invoke this function with the GeoStan ID property pre-set to a valid GeoStan ID, it will
not attempt to re-initialize GeoStan. This is how GSINITWP can be used to initialize DPV
and/or LACSLink after GeoStan has already been initialized with a previous call to
GSINITWP. If you intend to reuse the same initialization property list to initialize GeoStan
several times you must reset the GS-INIT-GEOSTAN-ID property back to zero, or completely
remove the property from the list. This informs GeoStan that you want a new GeoStan
instance when you call GSINITWP.
These initialization properties are required for GSINITWP to function correctly:
• GS-INIT-LICFILENAME
• GS-INIT-DATAPATH
• GS-INIT-PASSWORD
GSLACCLS
Clears the LACSLink global statistics.
Syntax
01 GSID PIC 9(9) BINARY.
01 RETURN-CODE PIC 9(9) BINARY
Arguments
Return Values
GS-SUCCESS
Prerequisites
GSLACINR
GSLACFPD
Formats a LACSLink false positive detail record from GSLACGFH.
Syntax
01 GSID PIC 9(9) BINARY.
01 GS-FALSE-POS-DETAIL-DATA
01 RETURN-CODE PIC 9(9) BINARY.
01 HEADER PIC X(len).
01 HEADER-SIZE PIC 9(9) BINARY VALUE len.
CALL "GSLACFPD" USING GSID, GS-FALSE-POS-DETAIL-DATA, GS-FPHD-SIZE,
HEADER, HEADER-SIZE, RETURN-CODE
Arguments
Return Values
GS-SUCCESS
Prerequisites
GSLACGFD
GSLACFPH
Formats a LACSLink false positive header record with data from GSLACGFH.
Syntax
01 GSID PIC 9(9) BINARY.
01 PDATAPIC ????
01 RETURN-CODE PIC 9(9) BINARY.
01 HEADER PIC X(len).
01 HEADER-SIZE PIC 9(9) BINARY VALUE len.
Arguments
HEADER Buffer containing the LACSLink false positive header after GSLACFPH
successfully completes. When the GeoStan application writes the
false positive report, it writes this buffer to the first line of the file.
Output.
Return Values
GS-SUCCESS
Prerequisites
GSLACGFD
GS-DPV-FALSE-POS == “Y”
GSLACGCS
Obtains the complete LACSLink statistics since the application initialized LACSLink.
Syntax
01 GSID PIC 9(9) BINARY.
01 GS-LACS-COMPLETE-STATS
01 RETURN-CODE PIC 9(9) BINARY
Arguments
Return Values
GS-SUCCESS
Prerequisites
GSLACINR
GSLACGFD
Retrieves the detail record for a LACSLink false positive report.
Syntax
01 GSID PIC 9(9) BINARY.
01 GS-FALSE-POS-DETAIL-DATA
01 RETURN-CODE PIC 9(9) BINARY.
Arguments
*PDATA Retrieves LACSLink statistics from the detail record for false positive
address matches using the data passed in GSLACGFH. This structure
contains the following:
GS-SUCCESS
Prerequisites
GSLACINR
GS-LACSLINK-IND == “F”
GSLACGFH
Retrieves LACSLink statistics for the header record for a LACSLink false positive report.
Syntax
01 GSID PIC 9(9) BINARY.
01 GS-FALSE-POS-HEADER-DATA
01 RETURN-CODE PIC 9(9) BINARY.
Arguments
Return Values
GS-SUCCESS
Prerequisites
GSLACINR
GS-LACSLINK-IND == “F”
GSMGET
Returns the address elements for the match candidate item specified.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 OUTPUT-STRING PIC X(USER LEN).
01 OUTLEN PIC S9(4) BINARY.
01 GSOPTIONS PIC 9(9) BINARY.
01 INDEX PIC 9(4) BINARY.
*
CALL “GSMGET” USING GSID, GSOPTIONS, INDEX, OUTPUT-STRING, OUTLEN,
GSFUNSTAT.
Arguments
OUTLEN Maximum size of the data GeoStan returns. If OUTLEN is shorter than
the data returned by GeoStan, GeoStan truncates the data and does
not generate an error. Input.
GS-SUCCESS
GS-ERROR
Prerequisites
GSNMULT
Notes
This procedure retrieves data from the GeoStan buffer for match candidatees. GeoStan
indicates a match candidate as the GSSFINDWP GS-ADDRESS-NOT-RESOLVED return code. It is
important to first test for an intersection match, since the variables are different for retrieving
intersection and non-intersection matches.
When using any street name variable (GS-NAME, GS-PREDIR, GS-POSTDIR, GS-TYPE) the
additional modifier GS-ALIAS is available to request specific alias information, rather than
preferred name information. For example, in Boulder, CO, Wallstreet is an alias for Fourmile
Canyon. The address 123 Wallstreet, Boulder CO 80301 matches to 123 Fourmile Canyon
Dr.
MOVE GS-NAME TO GSOPTIONS.
CALL "GSMGET" USING GSID, GSOPTIONS, ...
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 INDEX PIC 9(4) BINARY.
01 RANGE-HANDLE PIC S9(9) BINARY.
*
CALL “GSMGH” USING GSID, INDEX, RANGE-HANDLE, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSNMULT
Notes
This procedure can to extract more information about a possible match, then GSMGET. It
retrieves the range handle for the possible match indicated by the entry argument. Once
you have the correct range handle, you can retrieve information by using GSHGET. For a list
of elements returned by GSMGET or GSHGET, see “Variables for storing and retrieving data” on
page 279.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSNMULT” USING GSID, GSFUNSTAT.
Arguments
Return Values
A positive value indicates the number of match candidatees. GS-ERROR indicates an error.
Prerequisites
GSSFINDWP
Notes
This procedure returns the number of match candidatees found. Use GSMGET to retrieve the
actual address elements for each possible match. A return code from GSSFINDWP indicates a
possible match.
Syntax
01 FIND-PROP-LIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPFIND” USING FIND-PROP-LIST, PROPENUM, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
Notes
GS-SUCCESS returns if the property is found in the property list. GS-ERROR returns if the
property is not found.
GSPFIRST
Sets property iterator to first property.
Syntax
01 FIND-PROP-LIST PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPFIRST” USING FIND-PROP-LIST, GSFUNSTAT.
Arguments
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
Notes
Prior to iterating through the properties in a property list, this procedure sets the property list
iterator to the beginning of the list.
GSPFNEXT
Iterates to the next sequential property in the property list.
Syntax
01 FIND-PROP-LIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 PROPVALUE PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPFNEXT” USING FIND-PROP-LIST, PROPENUM, PROPVALUE, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
Notes
GeoStan only populates one of the PropValue union members. The populated union
member depends on the property output type. If there is no “next” entry, GeoStan returns an
error.
Syntax
01 STATUS-PROP-LIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 QBOOL PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPGETB” USING STATUS-PROP-LIST, PROPENUM, QBOOL, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPGETD
Retrieves a double property.
Syntax
01 STATUS-PROP-LIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 DOUBLE PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPGETD” USING STATUS-PROP-LIST, PROPENUM, DOUBLE, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPGETL
Retrieves an integer property.
Syntax
01 STATUS-PROP-LIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 INTL PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPGETL” USING STATUS-PROP-LIST, PROPENUM, INTL, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPGETST
Retrieves a string property.
Syntax
01 STATUS-PROP-LIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 INTL PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPGINFO
Retrieves information about a property.
Syntax
01 PROPENUM PIC S9(9) BINARY.
01 INT PIC S9(9) BINARY.
01 PROPLISTTYPE PIC S9(9) BINARY.
01 PSTR PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPGINFO” USING PROPENUM, INT, PROPLISTTYPE, PSTR, GSFUNSTAT.
Arguments
INT Output.
PSTR Output.
Return Values
GS-SUCCESS
GS-ERROR
GSPGSTRL
Retrieves the length of the string value of a property.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 INTLU PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPGSTRL” USING PROPLIST, PROPENUM, INTLU, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPLSTCR
Creates and initializes a property list for GeoStan initialization.
Syntax
01 INIT-PROP-LIST PIC S9(9) BINARY.
01 GS-INIT-PROP-LIST-TYPE PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPLSTRCR” USING INIT-PROP-LIST, GS-INIT-PROP-LIST-TYPE,
GSFUNSTAT.
Arguments
INIT-PROP-LISTPointer
to property list structure defined in copy member
GEOSTAN. Input and Output.
Return Values
GS-SUCCESS
GS-ERROR
Notes
This procedure creates/initializes a property list for use in GSINITWP or GSFINDWP. Any
property list created by this function needs to eventually be destroyed with GSPLSTDE.
GSPLSTRD
Reads the property list from a file or a character string.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 GS-CONST-STR PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPLSTRD” USING PROPLIST, NULL, GS-CONST-STR, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPLSTDE” USING PROPLIST, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
Notes
Find property lists cannot be destroyed until all searching is complete. Any list created by
GSPLSTCR must eventually be destroyed with GSPLSTDE.
GSPLSTGC
Retrieves the number of properties in a property list.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 INTL PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPLSTGC” USING PROPLIST, INTL, GSFUNSTAT.
Arguments
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPLSTWR
Writes the property list to a file or a character string.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 GS-CONST-STR PIC S9(9) BINARY.
01 PSTR PIC S9(9) BINARY.
01 INTSU PIC S9(9) BINARY
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPSETAS” USING PROPLIST, GS-CONST-STR, PSTR, INTSU, GSFUNSTAT.
Arguments
PSTR Output.
INTSU Output.
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
Notes
If the outfile argument value is “stdout”, then this function writes the properties to standard
out. If the outfiles argument is NULL, then this function writes the properties to the pBuffer
string.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPREMOV” USING PROPLIST, PROPENUM, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPRESET
Resets the property list to its default state.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPRESET” USING PROPLIST, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPSETAS
Sets a property where input name and value are both strings.
Note: If you intend to use the same Find property settings for all your address records, try
to construct your application to set the Find properties once before processing. It is
unnecessary to reset the properties again to the same values for each address
record. However, if required, you can change Find property values for individual
searches. Performance may be negatively affected by resetting for individual record
searches. Reset Find properties between address searches only if changing the Find
property value is necessary.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 GS-CONST-STR PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 GS-CONST-STR PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPSETAS” USING PROPLIST, GS-CONST-STR, GS-CONST-STR,
GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPSETB
Sets a boolean property.
Note: If you intend to use the same Find property settings for all your address records, try
to construct your application to set the Find properties once before processing. It is
unnecessary to reset the properties again to the same values for each address
record. However, if required, you can change Find property values for individual
searches. Performance may be negatively affected by resetting for individual record
searches. Reset Find properties between address searches only if changing the Find
property value is necessary.
Syntax
01 FIND-PROP-LIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 QBOOL PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPSETB” USING FIND-PROP-LIST, PROPENUM, QBOOL, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
Syntax
01 STATUS-PROP-LIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 DOUBLE PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPSETD” USING STATUS-PROP-LIST, PROPENUM, DOUBLE, GSFUNSTAT.
Arguments
STATUS-PROP-LISTPointer
to property list structure defined in copy member
GEOSTAN. Input.
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPSETL
Sets an integer property.
Note: If you intend to use the same Find property settings for all your address records, try
to construct your application to set the Find properties once before processing. It is
unnecessary to reset the properties again to the same values for each address
record. However, if required, you can change Find property values for individual
searches. Performance may be negatively affected by resetting for individual record
searches. Reset Find properties between address searches only if changing the Find
property value is necessary.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 INTL PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPSETL” USING PROPLIST, PROPENUM, INTL, GSFUNSTAT.
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPSETS
Sets a short integer property.
Note: If you intend to use the same Find property settings for all your address records, try
to construct your application to set the Find properties once before processing. It is
unnecessary to reset the properties again to the same values for each address
record. However, if required, you can change Find property values for individual
searches. Performance may be negatively affected by resetting for individual record
searches. Reset Find properties between address searches only if changing the Find
property value is necessary.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 INTS PIC S9(4) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSPSETS” USING PROPLIST, PROPENUM, INTS, GSFUNSTAT.
Arguments
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
GSPSETST
Sets a string property.
Note: If you intend to use the same Find property settings for all your address records, try
to construct your application to set the Find properties once before processing. It is
unnecessary to reset the properties again to the same values for each address
record. However, if required, you can change Find property values for individual
searches. Performance may be negatively affected by resetting for individual record
searches. Reset Find properties between address searches only if changing the Find
property value is necessary.
Syntax
01 PROPLIST PIC S9(9) BINARY.
01 PROPENUM PIC S9(9) BINARY.
01 C-CHARACTER-STRING.
05 CHAR-STRING PIC X(user len) VALUE 'your string here'.
05 FILLER PIC X(01) VALUE X'00'.
*
CALL “GSPSETST” USING PROPLIST, PROPENUM, C-CHARACTER-STRING,
GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSPLSTCR
Syntax
01 SIZE PIC S9(9) BINARY.
*
CALL “GSSCACHE” USING SIZE.
Arguments
0 Small
1 Medium
2 Large
Notes
You must call GSSCACHE before GSINITWP.
A smaller cache may slow the performance of GeoStan. Pitney Bowes recommends a
cache size of 2 for the best performance.
For changes in cache size settings to take effect, call GSSCACHE before GSINITWP.
GSSETSEL
Allows you to select a match from a set or match candidatees.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 INDEX PIC 9(4) BINARY.
*
CALL "GSSETSEL" USING GSID, INDEX, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
Prerequisites
GSMGET
Notes
After GSFINDWP returns GS-ADDRESS-NOT-RESOLVED, use GSNMULT and GSMGET to determine
which possible match is the correct match. Then use GSSETSEL to load that possible match
into the data retrieval buffers and retrieve it using GSDATGET.
This procedure returns GS-ERROR if the selection is out of range.
GSSLIC
Identifies license file and key.
Syntax
01 PASSWORD PIC S9(9) BINARY.
01 FILE-NAME PIC X(12).
*
CALL “GSSLIC” USING PASSWORD, FILE-NAME.
Arguments
FILE-NAME Fully qualified file name, including drive and path, of the file
containing the license information. Input.
Notes
Must call GSSLIC before GSINITWP.
GSSRELD
Allows you to specify the oldest acceptable date for GeoStan data files.
Syntax
01 RELEASE-DATE PIC X(8).
01 LSTATUS PIC 9(9) BINARY.
*
CALL "GSSRELD" USING RELEASE-DATE, LSTATUS.
Arguments
RELEASE-DATE Oldest allowable date for GeoStan data files, in the format
yyyymmdd. Input.
Notes
Must be called before GSINITWP.
Ignores any data files with dates older than the RELEASE-DATE parameter.
GSSNDX
Generates a soundex key for use in GSFFSET.
Syntax
01 LSTATUS PIC 9(9) BINARY.
01 NAME PIC X(USERLEN).
*
CALL "GSSNDX" USING NAME, LSTATUS.
Arguments
Return Values
Soundex key
Notes
This procedure generates a soundex key for a street name. Use it in conjunction with
GSFFSEG when you want to perform a soundex search. The soundex key, when combined
with a locale (state and city), is the primary index into the GeoStan databases. Searching by
soundex allows you to use your own scoring and matching mechanism for geocoding.
Note: A soundex match is a match based on the pronunciation of a field, not on the
spelling of a field.
GeoStan uses a modified version of the standard soundex algorithm first published by
Donald Knuth. The modifications made by Precisely include special treatment of certain
prefixes such as MAC, KN, and WR; special treatment for numeric street names; and an
encoding scheme to pack the key into the smallest number of bits.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 GSOPTIONS PIC S9(9) BINARY.
01 RANGE-HANDLE PIC S9(9) BINARY.
*
CALL "GSSSELR" USING GSID, RANGE-HANDLE, GSOPTIONS,
GSFUNSTAT.
Arguments
GS-ADDR-CODE Attempts to standardize and find an address geocode. You must set
this switch for address standardization. If this switch is not set,
GeoStan uses only the input ZIP and ZIP + 4 address elements.
GS-WIDE-SEARCH GeoStan considers all records matching the first letter of the street
name, rather than the soundex key on the street name. This results
in a wider search.
GS-Z9-CODE Attempts to find ZIP + 4 centroid match only (no ZIP+2 or ZIP).
GS-Z7-CODE Attempts to find ZIP+2 centroid match only (no ZIP + 4 or ZIP).
If you specify GS_ADDR_CODE and a ZIP centroid option, GeoStan only returns a ZIP Code
centroid match if an address geocode is not available.
You must use either GS_ADDR_CODE or GS_Z_CODE or both.(In general, you should specify
both.) These option settings are additive.
If you enter a pre-parsed address, it must contain the USPS abbreviations for street type,
predirectionals, and postdirectionals.
GS-SUCCESS
GS-ERROR
Prerequisites
GSFFSEG
Notes
This procedure allows you to get a range handle which points to the address range you
want to match to. Use this command to indicate that GSSFINDWP found the match, when in
fact the match is set to whichever range handle is passed through the RANGE-HANDLE
argument. You must specify the GSOPTIONS variable so that subsequent calls to GSDATGET
have the type of location information to return.
This procedure returns standardized results from a list generated by GSFFSEG / GSFNRANG.
This procedure performs a query procedure that lets the user choose from a list of possible
matches.
GSTERM
Terminates GeoStan.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL "GSTERM" USING GSID, GSFUNSTAT.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Notes
You must call GSTERM at the conclusion of a session to close files and release other
resources. It closes GeoStan and invalidates GSID. You cannot call any function except
GSINITWP after GSTERM.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 NUM-STRING PIC X(user len).
01 NUM-RANGE-LO PIC X(user len).
01 NUM-RANGE-HI PIC X(user len).
*
CALL “GSTSTRNG” USING GSID, NUM-STRING, NUM-RANGE-LO,
NUM-RANGE-HI, GSFUNSTAT.
Arguments
Return Values
Prerequisites
GSINITWP
Notes
This procedure tests to see if the house number is within the range defined by NUM-STRING-
HI and NUM-STRING-LO. It handles all valid house number patterns, such as
1A23B 1-23 AB
This procedure uses USPS rules defined in Publication 28, “Postal Addressing Standards”,
for determining whether number is in range or not. Some patterns are not comparable with
other patterns; for example, 123 is not comparable to a range of 1A01 to 1A99.
GSVAUXR
Validates an auxiliary file record.
*
CALL “GSVARU” USING GSID, GSFUNSTAT
Arguments
Return Values
GS-SUCCESS The record is valid and GeoStan will load the record. This includes
comment records; records whose first character is a semicolon.
GS-WARNING The record contains a non-fatal error and GeoStan will load the
record. Because this record has a problem, an input address may not
be able to match to the record in its current state, or the output data
from a match to the record may not be valid.
GS-ERROR The record contains a fatal error and GeoStan will NOT load the file.
Prerequisites
GSINITWP
GSVGSDDT
Validates the presence of data for specified states in the GSD data file.
Syntax
01 GSID PIC S9(9) BINARY.
01 STATES OCCURS 100 TIMES.
05 STATE-CODE PIC X(3).
05 STATE-COUNT PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
Arguments
GS-SUCCESS All states specified in STATES are present in the GSD data.
GS-GSD-DATA-MISSING One or more states specified in STATES are not present in the
GSD data.
Notes
If GeoStan did not find the GSD primary data for all the specified states, this function
creates an error in the error list retrievable using GSERRGTX. The error message code is 114
and the error message is “NO GSD DATA FOUND FOR STATE” and indicates which states
GeoStan did not find.
The state abbreviations and corresponding state FIPS codes are as follows:
FIPS FIPS
State Abbrev. Codea State Abbrev. Codea
Colorado CO 8 Ohio OH 39
Connecticut CT 9 Oklahoma OK 40
Delaware DE 10 Oregon OR 41
Idaho ID 16 Tennessee TN 47
Illinois IL 17 Texas TX 48
Indiana IN 18 Utah UT 49
Iowa IA 19 Vermont VT 50
Kansas KS 20 Virginia VA 51
Kentucky KY 21 Washington WA 53
Maine ME 23 Wisconsin WI 55
Maryland MD 24 Wyoming WY 56
Michigan MI 26 Guam GU 66
Mississippi MS 28 Palau PW 70
Nebraska NE 31
Nevada NV 32
New Hampshire NH 33
a Do not specify Minor Islands (UM, 74) or you will receive an error. This is defined as a FIPS
code, but the USPS does not generate data for this code.
The following pseudo FIPS codes support APO and FPO addresses:
Syntax
01 GSID PIC S9(9).
01 GS-EXTEND-CASS-DATA
01 DATA-SIZE PIC S9(9) BINARY.
01 OUTPUT-NAME PIC X(1).
01 GSFUNSTAT PIC S9(9) BINARY.
Arguments
Return Values
GS-SUCCESS
GS-ERROR
Prerequisites
GSINITWP
Notes
Before running a CASS report, verify you have loaded the GSZ file (ZIPMove data).
This procedure writes the CASS information to the header buffer using the data passed in
GSEXTENDCASSDATA. This structure contains the following:
01 GS-EXTEND-CASS-DATA.
05 GS-ECD-STRUCTVERSION PIC 9(9) BINARY.
05 GS-ECD-NRECS PIC 9(9) bINARY.
05 GS-ECD-NZIP4 PIC 9(9) BINARY.
05 GS-ECD-NZIP PIC 9(9) BINARY.
05 GS-ECD-NCARRT PIC 9(9) BINARY.
05GS-ECD-NDPBC PIC 9(9) BINARY.
05 GS-ECD-LISTNAME PIC X(20).
05 GS-ECD-VERSION PIC X(12).
05 GS-ECD-CERTIFICATIONDATE PIC X(24).
05 GS-ECD-PSEARCHPATH PIC X(256).
05 GS-ECD-TEMPLATENAME PIC X(256).
05 GS-ECD-NZ4CHANGED PIC 9(9) BINARY.
When you specify a version number for either version, Z4ChangeVersion, or LOTVersion,
GeoStan updates the corresponding fields in the template cass3553.frm file. For example,
entering a version number for Z4ChangeVersion prompts GeoStan to fill these fields on
cass3553.frm:
• B. List, 2b. Date list Processed Z4Change
• B. List, 3b. Date of Database Product Used Z4Change
• C. Output, 1b. Total Coded Z4Change Processed.
To develop CASS certified application in GeoStan, you must have the correct license
agreement with Pitney Bowes. You must also obtain CASS certification from the USPS for
every application developed in GeoStan. Using GeoStan does not make an application
CASS certified. For information on becoming CASS certified, see Appendix E: CASS
certification.
Syntax
01 GSID PIC S9(9) BINARY.
01 PZIP PIC X(USER LEN).
01 PZIP4 PIC X(USER LEN).
01 PDATE PIX X(USER LEN).
01 GSFUNSTATPIC S9(9) BINARY.
*
CALL “GSZ4CH” USING GSID, PZIP, PZIP4, PDATE, GSFUNSTAT.
Arguments
PZIP First five digits of the 9-digit ZIP Code to be tested. Input.
PZIP4 Last four digits of the 9-digit ZIP Code to be tested. Input.
PDATE Date of the GeoStan ZIP + 4 information file used to process the
record. The string’s format is MMYYYY (for example, 081998).
Input.
Return Values
GS-Z4-CHANGE
GS-Z4-NO-CHANGE
Prerequisites
GSINITWP
Notes
For ZIP4CH to work, the GeoStan GSL file must be in a directory listed in the PGPATHS
member of GSIINITSTRUCT when calling GSINITWP. The Z4Change file, which is generated by
the USPS, contains a record for every ZIP + 4 in the country. Each record contains twelve
flags that represent the last twelve months, starting with the current release date. Each of
these flags has a value of either True or False, indicating if the ZIP + 4 changed for that
monthly postal release. The GeoStan GSL file incorporates this information, which GSZ4Ch
references.
In this chapter
GeoStanTM Java API 395
GeoStanTM Java API
The following is a list of the classes that compose the GeoStan Java API. You can find
detailed documentation for the Java API in the directory where you installed GeoStan in
Geolib\JNI\JAVADOCS.
Class Description
DPVCompleteStats Obtains the complete DPV statistics since DPV was initialized.
FalsePositiveDetail Accesses the false-positive Detail record for DPV and LACSLink.
FalsePositiveHeader Accesses the false-positive Header record for DPV and LACSLink.
GeoStan Wraps the GeoStan library and accesses GeoStan functionality from
within Java. The GeoStan library standardizes and geocodes
addresses within the United States. The GeoStan library uses a C
API. The GeoStan class uses Java Native Interface (JNI) routines to
access the library.
Range Contains the range interval for house and unit numbers.
In this chapter
GeoStan .Net API 398
GeoStan .Net API
The following is a list of the classes that compose the GeoStan.Net API. You can find
detailed documentation for the .Net API in the directory where you installed GeoStanTM in
Geolib\DotNet\GsNetAssemblyPublic.chm.
Class Description
GeoPropsMetaData Contains information about each of the Init, Find, and Status
properties.
Range Contains the range interval for house and unit numbers.
In this appendix
This appendix discusses the deprecated C functions and COBOL
procedures.
Data types for C APIs 401
Enums for storing and retrieving data for C APIs 401
Deprecated C APIs 403
Variables for storing and retrieving data for COBOL functions 417
Deprecated COBOL procedures 419
Data types for C APIs
Please see “Data types” on page 95.
Syntax
GsFunStat GsFind( GsId gs, GsEnum options );
Arguments
options GsFind options. The following table contains valid enums. Input.
Address Processing
GS_ADDR_CODE Attempts to standardize and find an address geocode. Set this
switch if you want the address parsed and standardized. If this
switch is not set, GeoStan uses only the input ZIP and ZIP + 4
address elements.
GS_GEO_CODE Finds a geocode when address standardization is not possible.
If GeoStan cannot standardize an address, it uses the input ZIP
or ZIP + 4 to find a centroid match.
Search Options
GS_WIDE_SEARCH Considers all records matching the first letter of the street name,
rather than the soundex key on the street name, which allows a
wider search.
For Address processing, you must use either GS_ADDR_CODE or GS_Z_CODE (or both). These
settings are additive. For most purposes, you should specify the GS_ADDR_CODE, GS_Z_CODE,
and GS_GEO_CODE switch.
If you specify GS_ADDR_CODE and one of the Geocode level options, GeoStan only returns a
ZIP Code centroid match if the address is standardized but an address geocode is not
available.
For reverse geocoding, you need to set the reverse geocoding processing options:
GS_NEAREST_ADDRESS, GS_NEAREST_INTERSECTION, and GS_NEAREST_UNRANGED. The address
processing and multi-line address processing options are not valid for reverse geocoding.
Return Values
GS_LASTLINE_NOT_FOUND GeoStan did not find a match for city/state or ZIP Code.
Prerequisites
GsDataSet
Notes
If GeoStan cannot standardize and address, you can still retrieve normalized address
information, match codes, carrier routes, or other elements with GsDataGet. You can
retrieve alias information by calling GsMultipleGet with an index of 0.
Syntax
ints GsGetCoords( GsId gs, pintl pCoords, intsu maxPoints );
Arguments
Return Values
Number of points assigned to buffer.
Prerequisites
GsFind
Notes
This function returns an array of coordinates for the current feature found via GsFind. The
maximum number that GeoStan can return is 64 coordinate pairs, each pair consisting of
two long integers.
GeoStan scales coordinate pairs to integers with four decimal digits of precision. For
example, GeoStan returns a point at (-98.3, 29.7) as (983000, 297000). This is a different
scale from that expected by Spatial+ and similar GIS applications, which typically express
coordinates in millionths of degrees. You may need to scale coordinates obtained with this
function before using them as input to other software libraries or applications.
Syntax
intlu GsGetDatum ( GsId gs );
Arguments
Return Values
Current datum setting. Valid settings are DATUM_NAD27 and DATUM_NAD83 (default).
Prerequisites
GsSetDatum
Notes
This function returns the datum currently used by GeoStan in calculating address
coordinates. This setting affects only the numeric coordinates returned by GsDataGet for the
latitude and longitude of an address.
A datum is a mathematical model of the Earth used to calculate the coordinates on any
map, chart, or survey system. The North American Datum (NAD) is the official reference
ellipsoid used for the primary geodetic network in North America.
Although the return values are DATUM_NAD27 and DATUM_NAD83, note that TomTom uses
WGS84 instead of NAD83. These two coordinate systems are compatible.
Syntax
ints GsHandleGetCoords( GsId gs, GsSegmentHandle *pHandle,
pintl pCoords, intsu maxPoints );
Arguments
*pHandle Handle of the segment object for the coordinates returned. Input.
Prerequisites
GsFindFirst or GsFindNext
Notes
This function returns an array of coordinates for the segment to which handle points.
Example
/*This example retrieves coordinates for a street segment found using
GsFindFirstSegment.*/
#define MAX_POINTS 50
.
.
.
ints NumCoords;
intl Coords[MAX_POINTS *2];
Syntax
GsId GsInit_r ( GsInitStruct *gis );
Arguments
GS_FILE_SPATIAL_QUERY Loads spatial query files. If GeoStan cannot load the spatial
query files, GsInit_r fails. You can verify that GeoStan
loads the files by checking the IStatus parameter in
GsInit_r.
GS_FILE_ELEVATION_CODE Loads the optional Centrus Points elevation files.
GS_FILE_ADDR_CODE | GS_FILE_Z9_CODE
licFileName String [GS_MAX_STR_LEN] that specifies the path and name of the
license file, for example, c:\license\geostan.lic. Input.
status Pointer to a long (32 bit) integer that stores details on the
successfully initialized components. Output.
GeoStan uses the following constants to test each significant bit:
NULL GeoStan failed to initialize. This can occur for one of the following
reasons:
GeoStan did not find the necessary files. Check the Status
argument to view the files GeoStan found.
GeoStan could not find the license files or the passwords
were incorrect.
There is not enough memory for GeoStan to initialize.
All available GSD files have expired. Indicated by
GS_FILE_EXPIRED in the status argument.
Notes
GsInit_r is the recommended way to start a GeoStan application. It sets the license and
expiration date, and initializes the library.
You can use GsSetFilememoryLimit to control the amount of memory used for mapped files.
If you are using GsSetFilememoryLimit, call GsSetFilememoryLimit before calling GsInit_r.
Example
bool showAllMessages = true;
GsId gs;
char message[256];
char details[256];
intlu lDays;
GsInitStruct GIS;
/* Initialize GeoStan */
if ( gs == 0 || showAllMessages )
{
while ( GsErrorHas(gs) )
if ( gs == 0 )
{
/* GeoStan failed to initialize */
printf("Unable to initialize GeoStan library,
status = %04X.\n", GIS.status);
return(1);
}
}
/* GeoStan is initialized */
/* retrieve information about your GeoStan license */
lDays = GsFileStatusEx(gs, GS_STATUS_DAYS_REMAINING, 0, 0);
if ( lDays == DAYS_UNLIMITED )
{
printf("License is non-expiring.\n");
}
else
{
printf("License will expire in %d days.\n", lDays);
}
Syntax
GsFunStat GsInitDpv_r (GsId gs, DpvInitStruct *dpvInitStruct,
int structSize);
Arguments
dataAccess Indicates the type of files to load and how to access the files. The
following table contains the possible values. Input.
DPV_DATA_FULL_FILEIO Default. Files are not loaded into memory. Table access is
through file I/O.
DPV_DATA_FULL_MEMORY Files are loaded into memory. Use this option to gain
performance improvement by reducing repetitive file I/O.
DPV_DATA_SPLIT_FILEIO Use if your file is sorted by ZIP Code and you have limited
memory. Uses a split data format that separates the DPV data
file into multiple smaller files, based on the first 2 digits of the
ZIP Code. If you sort your mailing file by ZIP Code, you can use
this value to bring the relevant portion of the DPV file into
memory. This process uses 32 MB of storage, but reduces the
number of
I/O requests that normally occurs when you use the full DPV
data file.
memoryBufferSize Number of MBs used to load buffered files into memory. Input.
This option is only valid if dataAccess is not DPV_DATA_FULL_MEMORY. The following table
contains the possible values.
0 Default. Do not load DPV files into memory. Access is through file I/O.
pDirectory String that specifies the directory containing DPV data. Input.
Return Values
Notes
If you are using GsSetFileMemoryLimit to control the amount of memory used for memory
mapped files, you need to call GsInitDpv_r after GsSetFileMemoryLimit and before
GsInit_r.
If you are not using GsSetFileMemoryLimit, you need to call GsInit_r before calling
GsInitDpv_r.
Syntax
GsFunStat GsInitLACSLink_r ( GsId gs,
LACSLinkInitStruct *lacsInitStruct, init structSize);
Arguments
pDirectory String that specifies the directory containing LACSLink data. Input.
Return Values
Notes
If you are using GsSetFileMemoryLimit to control the amount of memory used for memory
mapped files, you need to call GsInitLACSLink_r after GsSetFileMemoryLimit and before
GsInit_r.
If you are not using GsSetFileMemoryLimit, you need to call GsInit_r before calling
GsInitLACSLink_r.
Syntax
intlu GsSetDatum ( GsId gs, intlu iNewDatum );
Arguments
Return Values
GS_ERROR GeoStan did not find any of the files for the requested datum.
GeoStan continues to use the current datum, and does not reset. Call
GsErrorGet to find out which datum files did not load.
Prerequisites
GsInit_r
Notes
Use GsSetDatum to select the datum you want GeoStan to use when returning address
coordinates via GsDataGet.This setting affects only the numeric coordinates returned by
GsDataGet for the latitude and longitude of an address.
WIN UNIX
GsSetFileMemoryLimit
Deprecated. Controls the amount of memory used for memory mapped files.
Syntax
int GsSetFileMemoryLimit (intlu megabytes)
Arguments
Return Values
GS_SUCCESS
Prerequisites
None
Notes
GsSetFileMemoryLimit helps you control the amount of memory GeoStan uses by providing
you with a way to set the memory limit for mapped files. Mapped files are the gsd, gsu, gsi,
cbsac.dir, finmbr.dat, and us.gsl files.
Call GsSetFileMemoryLimit before GsInit_r. GsSetFileMemoryLimit returns a warning if
called more than once per process.
If you are using DPV and LACSLink, you must call GsInitDpv_r and GsInitLACSLink_r after
GsSetFileMemoryLimit and before GsInit_r. Although the DPV and LACSLink files are not
memory mapped files, these libraries load large files that can cause GsInit_r to fail if not
enough memory is reserved.
To determine the amount of virtual bytes used by your process, set the file limit to 0 and run
your process.
Arguments
MatchMode Enum value indicating match mode type. The following table contains
valid enums. Input.
GS_MODE_EXACT Requires an exact name match. Generates the fewest number of possibles to
search.
GS_MODE_CLOSE (default) Requires a very close name match. Generates a moderate number
of possibles to search
GS_MODE_RELAX Requires a close name match. Generates the largest number of possibles to
search.
GS_MODE_CASS Requires a close name match. Generates the largest number of possibles to
search. This setting imposes additional rules to ensure compliance with the
USPS regulations for CASS software. For example, this mode disables
intersection matching, and matching to the User Dictionary matches for
standardization.
Return Values
Old match mode
– or –
-1 if the new match mode is invalid
Prerequisites
GsInit_r or GsClear
Notes
GsSetMatchMode affects how GsDataSet performs. For this reason, only call this function
immediately after GsInit_r or GsClear. The results are undefined if you call this function
with GsDataSet.
To emulate the Centrus Desktop modes, use the settings in the following table.
Centrus Desktop
(Match Mode) GsSetMatchMode GsFind
Tight GS_MODE_EXACT 1 | 2
Close GS_MODE_RELAX 1 | 2
Extended GS_MODE_RELAX 1 | 2 | 3 | 4
CASS GS_MODE_CASS 1 | 2 | 3
GeoStan Close Mode GS_MODE_CLOSE 1 | 2
GsFind then uses as its second argument the enums listed (in combination with a logical
OR). For example, in CASS mode, the second argument to GsFind is:
1 GS_ADDR_CODE
2 GS_Z9_CODE
3 GS_FINANCE_SEARCH
4 GS_WIDE_SEARCH
Note: For information on EWS, see Appendix E: CASS certification. For information on
DPV, see Appendix F: USPS Link products.
Changing GsSetMatchMode does not require the presence of the following files; however, to
achieve strict CASS compliance, these files must be present:
• Us.gsz
• Use.gsd and Usw.gsd
• Use.gsu and Usw.gsu
• DPV data
• EWS data (The file must be named ews.txt)
Syntax
ints GsSetMixedCase( GsId gs, ints bMixedCase );
Arguments
Return Values
Current setting for this option (the setting before the change).
Prerequisites
GsInit_r
Notes
This function determines if GeoStan returns standardized data in upper or mixed case. It
affects Firm name, all Address components, and City name. The USPS prefers upper case.
If you specify mixed case, generally only the first letter is set to upper case.
Syntax
qbool GsSetStreetCentroid( GsId gs, qbool GsStrCen );
Arguments
Return Values
Current setting for this option (the setting before the change).
Prerequisites
GsInit_r
Notes
When this feature is enabled, if a street name is encountered while geocoding, and there is
no matching address range, GeoStan will attempt to locate the street within the input ZIP
Code or city if there is no input ZIP Code. If GeoStan is able to locate the street, it will return
a geocode along the matched street segment rather than the geocode for the entered ZIP
Code or ZIP + 4.
If a street number is entered, GeoStan will return the coordinates of the end point of the
closest numeric street segment within the input ZIP Code. When there is no input ZIP Code,
the closest numeric street segment of all the ZIP Codes within the input city will be returned.
If no street number is entered, the centroid of a matching street segment within the input
ZIP Code will be returned. The centroid of a street segment for all the ZIP Codes within the
input city will be returned when there is no input ZIP Code.
match candidatees may be returned. More information about the returned segment(s) can
be obtained for either a single or a match candidate by calling GsMultipleGet().
This option is not available in CASS mode.
Buffer
leng GSDATA
Variable name th GSHGET SET GSDATAGET GSMGET
In Cen
pu Out ter
Street Segment Range t put line
GS- 4
CENTERLINE-
OFFSET
Offset distance
from the street
center for a
centerline match.
GS-DIST 3
Offset distance in
feet from centerline
and squeeze
distance from
intersection.
GS-OFFSE-DIST 4
Left and right offset
distance from the
street segments.
The range is 0 - 999
feet, with a default
of 50 feet.
GS-SEARCH- 5
DIST
Radius, in feet, that
GeoStan searches
for a reverse
geocode match.
The range is 0 -
5280 feet, with a
default value of 150
feet.
GS-SCORE 12
DEPRECATED.
GeoStan matching
score.
GS-SQUEEZE- 11
DIST
Distance, in feet, to
offset address-level
geocodes from the
street end points.
Default is 50 feet.
If the squeeze
distance is more
than half the
segment length,
GeoStan sets the
distance to the
midpoint of the
segment.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 GSOPTIONS PIC 9(9) BINARY.
*
CALL "GSSFIND" USING GSID, GSOPTIONS, GSFUNSTAT.
Arguments
You must use either GS-ADDR-CODE or one of the geocode level options (or both). These
option settings are additive. For most purposes, you should specify the GS-ADDR-CODE, GS-
GEO-CODE, and one of the geocode level options. If you specify GS-ADDR-CODE and one of the
geocode level options, GeoStan returns a ZIP Code centroid match only if the address is
standardized but an address geocode is not available.
Return Values
GS-ADDRESS-NOT-FOUND Did not find an address match or you have a metered license
and the GeoStan record count is depleted.
Prerequisites
GSDATSET
Notes
If GeoStan could not standardize an address, you can still retrieve normalized address
information, match codes, carrier routes, or other elements with GSDATGET. You can also
return alias information by calling GSMGET with an index of 0.
If you enter a pre-parsed address, it must contain the USPS abbreviations for street type,
predirectionals, and postdirectionals.
Before each find procedure, call GSCLEAR to reset the internal buffers. If you do not reset the
buffers, you may receive incorrect results with information from a previous find.
If you use both the reverse geocode and address line matching variables in the same call,
GeoStan displays an error. These types of finds are mutually exclusive.
GSGCRD
Deprecated. Retrieves coordinates for the street segment found via GSSFIND.
Syntax
01 GSIDPIC S9(9) BINARY.
01 GSFUNSTATPIC 9(4) BINARY.
01 COORDSOCCURS 64 TIMES.
Arguments
Return Values
Number of points assigned to buffer.
Prerequisites
GSSFIND
Notes
This procedure returns an array of coordinates for the current feature found via GSSFIND.
The maximum number that GeoStan can return is 64 coordinate pairs, each pair consisting
of two long integers.
GeoStan scales coordinate pairs to integers with four decimal digits of precision. Thus,
GeoStan returns a point at (-98.3, 29.7) as (983000, 297000). This is a different scale from
that expected by Spatial+ and similar GIS applications, which typically express coordinates
in millionths of degrees. You may need to scale coordinates obtained with this procedure
before using them as input to other software libraries or applications.
GSGDATUM
Deprecated. Returns the current datum setting.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL “GSGDATUM” USING GSID, GSFUNSTAT.
Arguments
Prerequisites
GSSDATUM
Notes
This procedure returns the datum currently used by GeoStan in calculating address
coordinates. This setting affects only the numeric coordinates returned by GSDATGET for the
latitude and longitude of an address.
A datum is a mathematical model of the Earth used to calculate the coordinates on any
map, chart, or survey system. The North American Datum (NAD) is the official reference
ellipsoid used for the primary geodetic network in North America.
Although the return values are DATUM_NAD27 and DATUM_NAD83, note that GTD uses WGS84
instead of NAD83. These two coordinate systems are compatible.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
01 SEGMENT-HANDLEPIC S9(9) BINARY.
01 MAXPOINTS PIC 9(4) BINARY.
01 COORDS OCCURS <nnn> TIMES.
05 COORD-X PIC S9(9) BINARY.
05 CORRD-Y PIC S9(9) BINARY.
*
CALL “GSHGCRD” USING GSID, SEGMENT-HANDLE, COORDS, MAXPOINTS,
GSFUNSTAT.
Arguments
SEGMENT-HANDLE Handle of the segment object for the returned coordinates. Input.
Return Values
Number of points assigned to the buffer.
Prerequisites
GSFFSEG or GSFNRANG
Notes
This procedure returns an array of coordinates for the segment identified in SEGMENT-HANDLE.
GSINIT
Deprecated. Initializes GeoStan.
Syntax
01 GSID PIC S9(9) BINARY.
01 LSTATUS PIC 9(9) BINARY.
01 GSOPTIONS PIC 9(9) BINARY.
* PPATH AND Z4DIR: ONLY VALID VALUES ARE BLANK OR "HIPER"
* THEY ARE ONLY USED IN GSINIT
*
Arguments
GS-FILE-SPATIAL-QUERY Loads spatial query files. If GeoStan cannot load the spatial
query files, GSINIT fails. You can verify that GeoStan loads
the files by checking the LStatus parameter in GSINIT.
GS-FILE-ELEVATION-CODE Loads the optional elevation files.
Except for a few cases, you should always specify GS-FILE-ADDR-CODE and GS-
FILE-Z9-CODE. Input.
PPATH List of paths to search for necessary files. Set this argument to either
“ ” or to “HIPER”, which loads the GSD file into hyperspace
(OS/390 extended memory). Other values are ignored. Input.
Z4DIR Name of the ZIP + 4 directory file. Set this argument to either “ ” or
to “HIPER”, which loads the Z9 file into hyperspace (OS/390
extended memory). GeoStan ignores other values. Input.
GS-FILE-EXPIRED All GSD files have expired (see Return Values section below).
Return Values
Returns a valid GSID if the system initializes correctly.
Returns 0 if GeoStan did not initialize.
GSINIT can fail for any of the following reasons:
• GeoStan did not find the necessary files. Check LSTATUS for the files GeoStan
successfully found (and by omission, the files not found).
• Not enough memory for GeoStan to initialize.
• All available GSD files have expired. In this situation, GSINIT returns GS-FILE-
EXPIRED in the LSTATUS argument.
Prerequisites
GSSLIC
Notes
Must be called before GSSCACHE, GSSLIC, or GSSRELD.
If you are using the GSSCACHE and GSSRELD procedures, You must call these before GSINIT.
You must call GSINIT before any other GeoStan procedure that uses the handle that GSINIT
returns.
GSDPVINR
Deprecated. Initializes GeoStan for DPV.
Syntax
01 GSID PIC S9(9) BINARY VALUE 0.
01 GSFUNSTAT PIC S9(9) BINARY.
01 STRUCT-SIZE PIC S9(9) BINARY.
01 W-HAVE-MESSAGE PIC S9(9) BINARY VALUE +0.
01 W-ERROR-MSG PIC X(256) VALUE LOW-VALUES.
01 W-ERROR-DETAIL PIC X(256) VALUE LOW-VALUES.
*
CALL 'GSDPVINR' USING GSID, GS-DPV-INIT-STRUCT, STRUCT-SIZE,
GSFUNSTAT.
Arguments
GS-DPV-FILE-SECURITY The DPV security file for initializing the DPV functionality.
GS-DIS-DATA-ACCESS Indicates the type of files to load and how to access the files.
The following table contains the possible values. Input.
DPV-DATA-FULL-FILEIO Default. Files not loaded into memory. All table access is
through file I/O.
Use this option for OS/390.
DPV-DATA-FULL-MEMORY All files loaded into memory. Use this option to gain
performance improvement by reducing repetitive file I/O.
DPV-DATA-SPLIT-FILEIO Separates the DPV data file into multiple smaller files, based
on the first 2 digits of the ZIP Code. If you sort your mailing file
by ZIP Code, you can bring the relevant portion of the DPV file
into memory. This process uses 32 MB of storage, but reduces
the number of I/O requests that normally occurs when you use
the full DPV data file. Use this option if your file is sorted by ZIP
Code and you have limited memory.
DPV-DATA-SPLIT- Use if your file is sorted by ZIP Code and you have limited
FILEIO memory. Uses a split data format that separates the DPV data
file into multiple smaller files, based on the first 2 digits of the
ZIP Code. If you sort your mailing file by ZIP Code, you can
use this value to bring the relevant portion of the DPV file into
memory. This process uses 32 MB of storage, but reduces the
number of
I/O requests that normally occurs when you use the full DPV
data file.
Prerequisites
GSINIT
Example
First initialize GeoStan for DPV.
**** WORKING STORAGE VARIABLES ******************
01 GSID PIC S9(9) BINARY VALUE 0.
01 GSFUNSTAT PIC S9(9) BINARY.
01 STRUCT-SIZE PIC S9(9) BINARY.
01 W-HAVE-MESSAGE PIC S9(9) BINARY VALUE +0.
01 W-ERROR-MSG PIC X(256) VALUE LOW-VALUES.
01 W-ERROR-DETAIL PIC X(256) VALUE LOW-VALUES.
COPY GSCONST.
IF GSFUNSTAT = GS-SUCCESS
DISPLAY 'DPV INITIALIZED SUCCESSFULLY'
ELSE
DISPLAY '********************************'
DISPLAY 'DPV FAILED TO INITIALIZE'
DISPLAY 'GSFUNSTAT IS:', GSFUNSTAT
DISPLAY 'GSID IS:', GSID
DISPLAY 'GS-DPV-INIT-STRUCT IS:', GS-DPV-INIT-STRUCT
DISPLAY 'STRUCT-SIZE IS:', STRUCT-SIZE
DISPLAY '********************************'
CALL 'GSERRHAS' USING GSID, W-HAVE-MESSAGE
PERFORM UNTIL W-HAVE-MESSAGE IS EQUAL TO ZERO
CALL 'GSERRGTX' USING GSID, W-ERROR-MSG, W-ERROR-DETAIL, GSFUNSTAT
DISPLAY 'W-ERROR-MSG:', W-ERROR-MSG
DISPLAY 'W-ERROR-DETAIL:', W-ERROR-DETAIL
CALL 'GSERRHAS' USING GSID, W-HAVE-MESSAGE
END-PERFORM.
After you have initialized DPV and called GSSFIND for an address, you can then call
GSDATGET and request any of the following output fields, which are included in the copy
member GSCONST:
GSSDATUM
Deprecated. Specifies the datum GeoStan uses to calculate address coordinates.
Syntax
01 GSID PIC 9(09) BINARY.
01 NEWDATUM PIC 9(09) BINARY.
01 GSFUNSTAT PIC S9(09) BINARY.
*
CALL “GSSDATUM” USING GSID, NEWDATUM, GSFUNSTAT.
Arguments
Return Values
GS-ERROR Did not find all of the files for the requested datum. GeoStan does
not reset the datum, and continues to use the current datum. Call
GSERRGET to find the datum files that were not loaded.
Prerequisites
GSINIT
Notes
A datum is a mathematical model of the Earth used to calculate the coordinates on any
map, chart, or survey system. The North American Datum (NAD) is the official reference
ellipsoid used for the primary geodetic network in North America.
Use GSSDATUM to select the datum you want GeoStan to use when returning address
coordinates via GSDATGET.
GSLACINR
Deprecated. Initialize GeoStan for LACSLink.
Syntax
01 GSID PIC S9(9) BINARY VALUE 0.
01 GSFUNSTAT PIC S9(9) BINARY.
01 STRUCT-SIZE PIC S9(9) BINARY.
01 W-HAVE-MESSAGE PIC S9(9) BINARY.
01 W-ERROR-MSG PIC X(256) VALUE LOW-VALUES.
01 W-ERROR-DETAIL PIC X(256) VALUE LOW-VALUES.
*
CALL 'GSLACINR' USING GSID, GS-LACSLINK-INIT-STRUCT, STRUCT-SIZE,
GSFUNSTAT.
Arguments
Return Values
Example
Initialize GeoStan for LACSLink.
*********** WORKING STORAGE VARIABLES ***********************
01 GSID PIC S9(9) BINARY VALUE 0.
01 GSFUNSTAT PIC S9(9) BINARY.
01 STRUCT-SIZE PIC S9(9) BINARY.
01 W-HAVE-MESSAGE PIC S9(9) BINARY.
01 W-ERROR-MSG PIC X(256) VALUE LOW-VALUES.
01 W-ERROR-DETAIL PIC X(256) VALUE LOW-VALUES.
COPY GSCONST.
IF GSFUNSTAT = GS-SUCCESS
DISPLAY 'LACS INITIALIZED SUCCESSFULLY'
ELSE
DISPLAY '********************************'
DISPLAY 'LACS FAILED TO INITIALIZE'
DISPLAY 'GSFUNSTAT IS:', GSFUNSTAT
DISPLAY 'GSID IS:', GSID
DISPLAY 'GS-LACSLINK-INIT-STRUCT:', GS-DPV-INIT-STRUCT
DISPLAY 'STRUCT-SIZE IS:', STRUCT-SIZE
DISPLAY '********************************'
CALL 'GSERRHAS' USING GSID, W-HAVE-MESSAGE
PERFORM UNTIL W-HAVE-MESSAGE IS EQUAL TO ZERO
CALL 'GSERRGTX' USING GSID, W-ERROR-MSG, W-ERROR-DETAIL, GSFUNSTAT
DISPLAY 'W-ERROR-MSG:', W-ERROR-MSG
DISPLAY 'W-ERROR-DETAIL:', W-ERROR-DETAIL
CALL 'GSERRHAS' USING GSID, W-HAVE-MESSAGE
END-PERFORM
After you have initialized LACSLink and called GSSFIND for an address, you can then call
GSDATGET and request any of the following output fields, which are included in the copy
member GSCONST:
• GS-LACS-FLAG
• GS-LACSLINK-IND
• GS-LACSLINK-RETCODE
GSSMIXED
Deprecated. Sets the casing of the returned information.
Syntax
01 GSID PIC S9(9) BINARY.
Arguments
MIXED-CASE Sets the casing of the returned value; either 0 for upper case (default)
or1 for mixed case. Input.
Return Values
Current setting for this option (the setting before the change).
Prerequisites
GSINIT
Notes
Casing affects the firm name, all address components, and City name. The USPS prefers
upper case.
If you specify mixed case, generally only the first letter is set to upper case.
GSSMM
Deprecated. Controls the matching mode used by GSSFIND.
Syntax
01 GSIDPIC S9(9) BINARY.
01 MATCH-MODEPIC 9(4) BINARY.
01 GSFUNSTATPIC 9(4) BINARY.
*
CALL "GSSMM" USING GSID, MATCH-MODE, GSFUNSTAT.
Arguments
MATCH-MODE Variable value indicating match mode type. The following table
contains the valid variables. Input.
Return Values
Old match mode, or a -1 if the new match mode entered is invalid.
Prerequisites
GSINIT or GSCLEAR
Notes
GSSMM affects how GSDATSET performs. For this reason, call this procedure only immediately
after GSINIT, or after a GSCLEAR. If you call this procedure after loading data with GSDATSET,
the results are undefined.
GSSTRCEN
Deprecated. Used to enable street locator geocoding as an automatic geocoding fallback.
Syntax
01 GSID PIC S9(9) BINARY.
01 GSSTRCEN PIC S9(9) BINARY.
01 GSFUNSTAT PIC S9(9) BINARY.
*
CALL "GSSTRCEN" USING GSID, GSSTRCEN, GSFUNSTAT.
Arguments
Return Values
Current setting for this option (the setting before the change).
Prerequisites
GSINIT
In this appendix
Extracting data directly from GSD files 435
Data structure and concepts 435
Street, segment, and range handles 436
FindFirst and FindNext functions 437
Search query 437
Code example 437
You can access all of the information contained within the GSD files via the functions in
GeoStan. While you need sophisticated matching algorithms to facilitate address
standardization and geocoding, there may be other purposes that require data access in a
more direct method. The GsFindFirst__, GsFindNext__, and GsHandleGet functions provide
a way to directly access information. This section documents how to use these functions,
and provide information on the following topics:
• Extracting data directly from GSD files
• Data structure and concepts
• Street, segment, and range handles
• FindFirst and FindNext functions
• Search query
• Code example
Note: GsFindFirst__, GsFindNext__, and GsHandleGet are advanced features not normally
used for most standardization and geocoding applications.
There can be overlap within Range Objects. For example, one Range Object may
contain house numbers between 100 to 198, while another Range Object may contain
house numbers between 150 and 198. This frequently happens with high-rise Range
Objects.
Because records may exist in one source that are not present in the other, there are
occasions in which GeoStan may present only TIGER or USPS information. If Precisely
was unable to match any TIGER records to a USPS record, a Segment Object may not
contain any of the location and Census information. In this case, address geocode and
Census Block information is not available. Conversely, there are records within TIGER that
Precisely cannot match to any USPS records. In this case, no Range Objects may exist for
that segment, and therefore GeoStan cannot standardize the address and cannot return the
information available in the Range Object. This type of match does not produce a mailable
address.
is undefined.
is valid and is used to promote a street handle to a segment handle for entry into the Find
routine. The segment handle osoundexf hSegment is still undefined, but that
hSegment.hStreet can be used as a valid street handle (assuming hMyStreet was a
valid handle to begin with).
Note: All handles are invalid after a call to GSCLEAR.
Search query
With GsFindFirstStreet you can define options that narrow the matches returned by
GeoStan.
When you use GsFindFirstStreet you use the city or ZIP Code to set the finance area of a
search. A finance area can contain more than one ZIP Code or city. Therefore, GeoStan
may return results that are in the finance area specified by the locale you entered, but the
result may not be in the actual ZIP Code or city you entered.
You can narrow the number of matches GeoStan returns by setting the whole or partial
street name. For example, if you are searching for “Apple,” GeoStan returns the streets
within the finance area with the names of “APPLE,” “APPLETON,” and “APPLE
ORCHARD.” You can set the street name based on the actual spelling of the name, or by
the soundex value of the name.
You can further narrow the matches returned by GeoStan by indicating a house number. If
you specify a house number, GeoStan only returns matches that have ranges that include
the house number.
Code example
The following example searches ZIP Code 80301 for all streets beginning with “A.” Note
how you can convert a street or segment handle to a range handle for use with
GsHandleGet to return Street or Segment information.
/* This example searches ZIP Code 80301 for streets beginning
with “A” and no specific house number. */
/* Use GsFindFirstStreet to get the first street handle that matches the
criteria. */
int iStat = GsFindFirstStreet( gs, &hStreet, GS_ZIP_SEARCH, “80301”, “A”,
““ );
while( iStat == GS_SUCCESS )
{
/* We got a valid street handle which we convert to a range handle so
that we can use GsHandleGet retrieve information to show the user.
Even though we converted to a range handle, it really is still just a
street handle, so we can only access those elements that are valid at
the street level. See Appendix A for a complete list of valid elements
for each handle type. */
hSegment.hStreet = hStreet;
hRange.hSegment = hSegment;
GsHandleGet( gs, GS_PREDIR, &hRange, tempstr, sizeof(tempstr) );
printf( “Street: %s “, tempstr );
GsHandleGet( gs, GS_NAME, &hRange, tempstr, sizeof(tempstr) );
printf( “%s “, tempstr );
GsHandleGet( gs, GS_TYPE, &hRange, tempstr, sizeof(tempstr) );
printf( “%s “, tempstr );
GsHandleGet( gs, GS_POSTDIR, &hRange, tempstr, sizeof(tempstr) );
printf( “%s\n”, tempstr );
In this appendix
This appendix discusses the sample applications, Geotest and
Geocoder, provided with GeoStan.
Geotest 441
Geocoder 447
Note: The following instructions cover using the sample application on
Windows unless otherwise specified.
Geotest
Geotest is a sample program that demonstrates the functionality of GeoStan. Geotest is
located in the 32bit or 64bit (Windows) or samples (UNIX) directory. The sample code is
located in the samples (UNIX) or Ms_c (Windows) directory.
You can run geotest without any arguments using the test.ini file or in interactive mode
with arguments on the command line.
Configuring geotest
If you do not specify any arguments on the command line when initializing geotest, geotest
initializes using the information in the test.ini file. You need to modify the test.ini file to
fit the configuration of your system. You can find this file in the directory where you installed
GeoStan in Test_fls.
The format of the test.ini file consists of the following lines:
Line 2 Search path and file name for the ZIP + 4 file (Us.z9).
Line 3 Search path and file name for GeoStan license file
(Geostan.lic).
Line 14 (Optional) Sets the path to a file that contains all of your find
properties.
Using geotest
You can run geotest using geotest.exe located in the platform-specific file where you
installed GeoStan, or you can run geotest by specifying arguments on a command line.
Command Line
Note: Optional arguments in parentheses override positional arguments. All optional
arguments must have a space following the option indicator.
Command line usage format:
geotest searchPath ZIP4File licenseFile password (-sp searchpath -z
ZIP4File -l licenseFile -lpw password) [-dp DPVDataDir -dk
DPVSecurityKey] [-lp LACSLinkDataDir -lk LACSLinkSecurityKey] [-tp
SuiteLinkDataDir] [-rp RDIDataDir][-gc] [-fml fileMemoryLimit] [-q]
[-i initProps] [-c cacheSize] [-fp findPropsPath]
where:
Z - GS_INIT_OPTIONS_Z9_CODE us.z9
S - GS_INIT_OPTIONS_SPATIAL_QUERY finmbr.dat
E - GS_INIT_OPTIONS_ELEVATION_CODE *.elv
P - GS_INIT_OPTIONS_APN_CODE *.apn
C - GS_INIT_OPTIONS_ZIP_PBKEYS zipsmld.gsd
D - GS_INIT_OPTIONS_DEBUG_LOG
SuiteLinkDataDir (-tp) The name of the directory containing SuiteLink data
RDIDataDir (-rp) The name of the directory containing RDI data
quitMainMenu A q or Q to indicate how to exit the Main menu
findPropsPath (-fp) The fully-qualified path to a forward geocoding find properties file.
-gc An option to initialize Geotest with the same GsInit values as Geocoder.
If any of the setup criteria does not initialize correctly, a list of problems displays. Check and
correct all of the listed problems and rerun geotest.
The Geotest Main Menu displays when all configurations are correct (sample menu shown
below).
Match an address
Prompts for an address to standardize and geocode. Returns
a matched address or a list of possible matches.
Query Prompts for a ZIP Code or city and state, then asks if you want
to search by street by name or soundex. If you want to output
to a file, enter the file name at the Name prompt.
Configure Provides a way for you to configure the matching and output
of geotest.
Z4Change Prompts for ZIP Code information, then indicates if the ZIP +
4 has changed since you last processed the address.
Generate Soundex
Prompts for a string and returns a soundex value.
Test range Prompts for the house number and the low and high house
number in the range to determine if the house number falls
within a range.
Verify Aux File Prompts for the path of the auxiliary file to verify if any error
exists in the file.
Geographic Geocoding
Prompts for a city, a county, and a state to provide returns for
CloseFlag, City\County\State, State, ResultCode, FIPS,
LocationCode, Lat, and Long.
Query Cities Prompts for a city name, full or partial, or a zip code, 3- or 5-
digits. Returns the cities that match your input.
For more information about these options, see the associated section referenced by the
links in the following table.
Using geocoder
Geocoder is located in the platform-specific directory where you installed GeoStan. You need
to modify Gcode.fmt to match your file system structure prior to running geocoder. Sample
format files and input files are located in the Test_fls directory (Windows) and
Common/Test_fls directory (UNIX).
inputFile Path and name of the input addresses to process. The file
must be a fixed length ASCII text file. You can specify a dash
(-) or stdin in place of the format file.
outputFile Path and name of a new text file to hold the processed
records. The output file normally has the same format as the
input file, with the possible addition of fields at the end of each
record. You can specify a dash (-), stdout, or stderr in place
of the format file.
logfile
(Optional). Name of the log file where geocoder writes all
messages to the specified log file instead of stdout. If
specified, this must be the fourth parameter on the command
line. geocoder disables the progress messages unless there is
an override in the format file. You can specify a dash (-),
stdout, or stderr in place of the log file.
The following are optional parameters you can enter at the command line for different
processing of your input and output.
/r <Report File name> To specify a report file name, enter r/ <Report File
name>, where the desired file name replaces what is between
the <> in the command line. The /r command line option
overrides the "reportFile" keyword in the format file.
Scenario Command
Z4 change processing and the log geocoder formatFile inputFile outputFile logFile /z mmyyyy
file enabled
Input file read from stdin, output geocoder formatFile - - logfile /z 062006
file written to stdout, logfile
enabled, and Z4 change
processing enabled
Keyword Description
approxPBKey In the event that a matched address does not have an associated
PreciselyID unique identifier, approxPreciselyID is used to return the
PreciselyID unique identifier of the nearest address with an associated
PreciselyID unique identifier.
• 0 - Default. Disable.
• 1 - Enable return of the PreciselyID unique identifier of the nearest
address with an associated PreciselyID unique identifier.
audFile Fully qualified path and filename for audit record redirection, which is
required if not set to 0. A keyword is required if set to 1.
NOTE: On z/OS you do not need to include a filename; code only the
letter x.
CASSFile Fully qualified path and filename for CASS Report. (Required if
matchMode is set to 4.)
NOTE: On z/OS you do not need to include a filename; code only the
letter x.
CASSTemplateFile Fully qualified filename of the CASS 3553 form used to generate the
report. Required in CASS mode.
NOTE: On z/OS you do not need to include a filename; code only the
letter x.
NOTE: On z/OS you do not need to include a filename; code only the
letter x.
NOTE: Not available with User Dictionaries. Not valid in CASS match
mode.
extendedMatchCode Specifies whether to return the Extended Match Code (4th hex digit).
• 0 = Default. Disabled
• 1 = Extends match code to indicate house, unit number and unit type
matching.
firstLetterExpanded Expands address search abilities to account for a missing or wrong first
letter in the street name.
• 0 = Disabled (standard default).
• 1 = Enabled.
inReclen Required. Record length of input file. Minimum line length to read if
inRecType is 1.
NOTE: On z/OS you do not need to include a filename; code only the
letter x.
MailerCity City where your organization resides. Required for DPV and LACSLink
initialization.
MailerName Name of your organization. Required for DPV and LACSLink initialization.
MailerZip 9-digit ZIP Code where your organization resides. Required for DPV and
LACSLink initialization.
mustMatchMainAddr Custom matching option to ensure street name, predir, postdir, and type
match exactly.
• 0 = Disabled (default).
• 1 = Enabled.
NOTE: On z/OS you do not need to include a filename; code only the
letter x.
offsetDist Deprecated. The number of feet GeoStan will squeeze streets when
interpolating the geocode for a house number. In addition, the number of
feet used to set the geocode off the street.
Use squeezeDist and setbackDist keywords instead.
NOTE: On z/OS you do not need to include a filename; code only the
letter x.
path Required. Search path for GeoStan data files; delimited with semicolons.
For example c:/;d:/geocode.
NOTE: On z/OS you do not need to include a filename; code only the
letter x.
printCandidates Return all candidate matches, each on a separate line. This will increase
the length of the output file.
• 0 – Disables (default).
• 1 – Enabled and returns a maximum of n candidates
reportFile Fully qualified path and file name for statistics report file. If this keyword
is not present, geocoder writes the report file geocoder.rpt to the
current working directory.
NOTE: On z/OS you do not need to include a filename; code only the
letter x.
reverseGeoAddress Specifies how addresses and unranged streets are processed with
reverse geocoding.
• 0 – Default. Does not match to an address.
• 1 – Matches to points and interpolated addresses, but does not match
to any unranged segments.
• 2 – Matches to all types of street segments.
setbackDist The number of feet GeoStan will set the geocode back off the street
segment when interpolating a geocode from a house number on a
segment.
Incompatible with offsetDist. Sets the value for
GS_FIND_STREET_OFFSET.
showMessages • 0 – Supresses messages from GsErrorGetEx (default).
• 1 – Prints messages from GsErrorGetEx.
showProgress Specifies the frequency with which the application writes status
messages indicating the number of processed records.
• 0 – No progress message.
• 10 – Default. Display messages every 10 records.
NOTE: By default, the program sets this value to 0 if the command line
specifies a log file or if the application is running under z/OS.
z4ChangeDate Date of the Centrus data media used to process the address file, in the
format mmddyy. For z/OS only.
z9dir Optional. Full name and path of the Z9 file, for example d:/us.z9. See
useCentroids above.
start_pos Offset for the first character of the field. The first position of the
specified offset is one.
Note: If you are processing in CASS mode, geocoder alerts you if you do not output
required CASS fields and have the parameter CASSFile initialized with the path and
filename for the CASS report file. Once complete, geocoder writes the data to the file
specified.
Input fields
Field Description
inAddr2 Second address line. When using this field, set multiLine to 0. Use
multiPref to specify a preference for P.O. Box or street address. Ignore
if processing in CASS mode.
inLine1 - inLine6 Multiline mode input fields. When using, set multiLine to 1.
inZip4 ZIP + 4.
Output fields
Length
(with null
Field terminator) Description
centerlineDist 8 Distance between the input point and the centerline in feet
outAuxUserData 301 User data from the auxiliary file. Blank if no auxiliary file.
outMCDNumber 6 Minor Civil Division number from the auxiliary file. Blank if no
auxiliary file match.
outTFID 10 TIGER Face Identifier. This field can be used to match to all
Census geocodes using external data; 0 if none.
outUACE 6 TIGER Urban Area Identifier. Defines the urban area if any;
0 if none.
outZIP4 4 ZIP + 4
Note: When you redirect output data and specify a CASS header in the format file,
geocoder writes the CASS header as the last record of the output file instead of the
first record.
reverseGeoAddress Specifies how addresses and unranged streets are processed with
reverse geocoding.
• 0 – Default. Does not match to an address.
• 1 – Matches to points and interpolated addresses, but does not
match to any unranged segments (such as highways).
• 2 – Matches to all types of street segments.
searchDist Used for reverse geocoding. Defines, in feet, the search area.
Geocoder returns the same output fields for reverse geocoding as for forward geocoding.
For field definitions, see “Input and output keywords” on page 455.
Geocoder returns the same location codes for reverse geocoding as for forward geocoding;
however, there are match codes that are specific to reverse geocoding as follows:
For more information, see Appendix D: Status codes.
Audit Report
If the keyword audit is greater than 0 in the FMT file, geocoder outputs the audit file. For
example if audit = 1000, geocoder writes every 1000th record to the audit output file. The
file is named using the path and filename initialized with audFile in the format file.
The information shown in both the Input Address and Output Results sections is dependent
on the keywords you specified in the FMT file. The match code and location code is
included at the end of each audit entry for troubleshooting purposes.
Non-standardized File
If the keyword nonStand is greater than 0 in the format file geocoder generates the non-
standardized output file. The file is named using the path and filename initialized as the
nStdFile keyword in the format file. geocoder sends all records that receive an Exxx match
code to this file instead of to the output file. Initializing the nonStand keyword overrides a
keyword keepNoMatch setting of 0 and outputs the non-standardized records to nStdFile.
Statistics Report
geocoder creates a status report file (geocoder.rpt by default) in the current working
directory with every pass of the data. The file contains a statistical compilation of the most
recent pass of geocoder. Each successive geocoder pass with the same format file
overwrites the previous status report file. If you want to maintain historical data, backup this
file prior to the next geocoder pass or modify the reportFile keyword in the format file.
In this appendix
This appendix contains the different status codes returned by
GeoStan.
Status codes overview 468
Match codes 468
Location codes 476
Status codes overview
This appendix contains the different status codes returned by GeoStan through
GS_MATCH_CODE and GS_LOC_CODE used with GsDataGet.
• Match codes
• Definitions for 1st-3rd hex digit match code values
• Definitions for Extended Match Code (3rd hex digit) values
• Definitions for the Reverse PBKey Lookup “Vhhh” return codes
• Definitions for “Ennn” return codes
• Correct lastline match codes
• Location codes
• Address location codes
• Street centroid location codes
• ZIP + 4 centroid location codes
• Geographic centroid location codes
For more information on MapMarker result codes, refer to the MapMarker documentation.
Match codes
GeoStan returns match codes that indicate the portions of the address that matched or did
not match to the GeoStan Directory file. If GeoStan could not make a match, the match
code begins with "E" and the remaining digits indicate why the address did not match. The
digits do not specifically refer to which address elements did not match, but rather why the
address did not match.
The following table contains the match code values. You can find a description of the hex
digits for the different match codes in the table following the match code table.
Code Description
Ahhh Same as Shhh, but indicates match to an alias name record or an alternate record.
Chh Street address did not match, but located a street segment based on the input ZIP
Code or city.
D00 Matched to a small town with P.O. Box or General Delivery only.
Qhhh Matched to USPS range records with unique ZIP Codes. CASS rules prohibit altering
an input ZIP if it matches a unique ZIP Code value.
Shhh Matched to USPS data. This is considered the best address match, because it
matched directly against the USPS list of addresses. S is returned for a small number
of addresses when the matched address has a blank ZIP + 4.
Uhhh Matched to USPS data but cannot resolve the ZIP + 4 code without the firm name or
other information. CASS mode returns an E023 (multiple candidates for a match)
error code.
Vhhh Matched to MLD and DVDMLDR using Reverse PBKey Lookup. For match code
values, see Definitions for the Reverse PBKey Lookup “Vhhh” return
codes.
Xhhh Matched to an intersection of two streets, for example, “Clay St & Michigan Ave.” The
first hex digit refers to the last line information, the second hex digit refers to the first
street in the intersection, and the third hex digit refers to the second street in the
intersection.
NOTE: The USPS does not allow intersections as a valid deliverable address.
Yhhh Same as Xhhh, but an alias name record was used for one or both streets.
a Zh may be returned if Correct Last Line is set to True. For more information see Correct
lastline match codes and Using correct lastline.
Code In first hex position means: In second and third hex position means:
3 City and ZIP Code changed. Street type and predirectional changed.
5 State and ZIP Code changed. Street type and postdirectional changed.
7 State, City, and ZIP Code Street type, predirectional, and postdirectional
changed. changed.
9 ZIP and ZIP + 4 changed. Street name and street type changed.
B City, ZIP, and ZIP + 4 changed. Street name, street type, and predirectional
changed.
D State, ZIP, and ZIP + 4 changed. Street name, street type, and postdirectional
changed.
E State, City, and ZIP + 4 changed. Street name, predirectional, and postdirectional
changed.
F State, City, ZIP, and ZIP + 4 Street name, street type, predirectional, and
changed. postdirectional changed.
0 Matched on all address information on line, including Unit Number and Unit
Type if included.
8 Matched on Unit Number and Unit Type if included. House Number changed or
ignored.
9 Matched on Unit Number and Unit Type if included. House Number changed or
ignored. Extra information not considered for matching moved to GS_ADDR2 or
GS_MAIL_STOP field.
V002 Match made using input pbKey. One Standard, some Enhanced
point address variations results returned depending on license.
Code Description
Ennna Indicates an error, or no match. This can occur when the address
entered does not exist in the database, or the address is badly formed
and cannot be parsed correctly. The last three digits of an error code
indicate which parts of an address the application could not match to
the database.
nnn=028 Record also matched EWS data, therefore the application denied the
match.
nnn=040 No match found using input PBKey with Reverse PBKey Lookup.
nnn=041 Not licensed to return Enhanced point address(es) found for input
pbKey. Additional Reverse PBKey Lookup license option required to
return results.
a Ehnn may be returned if Correct Last Line is set to True. For more information, see Correct lastline
match codes and Using correct lastline.
Code Description
Ehnn Indicates an error, or no match. This can occur when the address
entered does not exist in the database, or the address is badly
formed and cannot be parsed correctly. The second digit of the error
code is a hex digit which details the changes that were made to the
last line information to correct the lastline. The last two digits of an
error code indicate which parts of an address the application could
not match to the database.
nn=28 Record also matched EWS data, therefore the application denied
the match.
3rd and 4th characters Digit indicating other qualities about the location.
Code Description
AGn Indicates an auxiliary file for a geocode match where n is one of the
following values:
n=2 The geocode is an interpolated address along a segment, and the side
of the street cannot be determined from the data provided in the
auxiliary file record.
AIn The correct segment is inferred from the candidate records at match
time.
ASn House range address geocode. This is the most accurate street
interpolated geocode available.
AIn, ASn, and ACnh share the same values for the 3rd character “n” as follows:
n=1 Street side is unknown. The Census FIPS Block ID is assigned from the
left side; however, there is no assigned offset and the point is placed
directly on the street.
NOTE: Only the second case is valid for non-TIGER data because
segment range interpolation is only completed for TIGER data.
h=0 Represents the interpolation between 2 points, both coming from User
Dictionaries.
h=1 Represents the interpolation between 2 points. The low boundary came
from a User Dictionary and the high boundary, from a non-User
Dictionary.
h=2 Represents the interpolation between 1 point and 1 street segment end
point, both coming from User Dictionaries.
h=4 Represents the interpolation between 2 points. The low boundary came
from a non-User Dictionary and the high boundary from a User
Dictionary.
h=5 Represents the interpolation between 2 points, both coming from non-
User Dictionaries.
h=7 Represents the interpolation between 1 point and 1 street segment end
point and both came from non-User Dictionaries.
h=8 Represents the interpolation between 1 street segment end point and
1 point, both coming from User Dictionaries.
h=9 Represents the interpolation between 1 street segment end point (low
boundary) and 1 point (high boundary). The low boundary came from a
User Dictionary and the high boundary from a non-User Dictionary.
h=B Represents the interpolation between 2 street segment end points. The
low boundary came from a User Dictionary and the high boundary from
a non-User Dictionary.
h=C Represents the interpolation between 1 street segment end point (low
boundary) and 1 point (high boundary). The low boundary came from a
non-User Dictionary and the high boundary from a User Dictionary.
h=D Represents the interpolation between 1 street segment end point and
1 point, both coming from non-User Dictionary.
h=E Represents the interpolation between 2 street segment end points. The
low boundary came from a non-User Dictionary and the high boundary
from a User Dictionary.
n=1 The geocode is placed along a single street segment, midway between
the interpolated location of the first and second input house numbers in
the range.
n=2 The geocode is placed along a single street segment, midway between
the interpolated location of the first and second input house numbers in
the range, and the side of the street is unknown. The Census FIPS
Block ID is assigned from the left side; however, there is no assigned
offset and the point is placed directly on the street.
n=4 The input range spans multiple USPS segments. The geocode is
placed on the endpoint of the segment which corresponds to the first
input house number, closest to the end nearest the second input house
number.
n=7 Placeholder. Used when the starting and ending points of the matched
segment contain the same value and shape data is not available.
1st character Always “C” indicating a location derived from a street segment.
2nd character Census ID accuracy based on the search area used to obtain matching
Street Segment.
3rd character Location of geocode on the returned street segment.
The following table contains the values and descriptions for the location codes.
Character
position Code Description
2nd Character
3rd Character
C Segment Centroid.
1st character Always “Z” indicating a location derived from a ZIP centroid.
2nd character Census ID accuracy.
3rd character Location type.
4th character How the location and Census ID was defined. Provided for completeness,
but may not be useful for most applications.
The following table contains the values and descriptions for the location codes.
Character
position Code Description
2nd Character
3rd Character
4th Character
1st character Always “G” indicating a location derived from a geographic centroid.
2nd character Geographic area type.
The following table contains the values and descriptions for the location codes.
Character
position Code Description
2nd Character
M Municipality (city).
C County.
S State.
In this appendix
CASS certification overview 485
CASS report 485
Obtaining USPS CASS certification for applications 485
Modifying the CASS 3553 report template 487
CASS certification overview
The USPS® Coding Accuracy Support System (CASS™) is a service offered to mailers,
service bureaus, and software vendors that improves the accuracy of delivery point codes,
ZIP+4 Codes, 5-digit ZIP Codes, and carrier route information on mail. CASS provides a
common platform to measure the quality of address matching software and useful
diagnostics to correct software problems.
Note: For more information on CASS contact the USPS National Customer Support center
at http://ribbs.usps.gov/files/cass/ or 1-800-642-2914.
To receive greater discounts on bulk mail postage, you can process your address list with
USPS-certified address standardization software; reffered to as CASS certification. To
qualify for the CASS certification™ discount, you must generate a CASS report with the
standardization software during processing and submit the completed form with the mailing.
CASS report
USPS-certified address standardization software generates the CASS form PS3553 report,
commonly refered to as the CASS report, during mailing list processing.
To generate a CASS report, the software compiles numerous statistics during processing,
such as the number of 5-digit ZIP Codes and ZIP+4 Codes assigned to records in the
address file. The application writes this information, along with other information required by
the USPS, to an ASCII text file.
Note: You must use the DPV, SuiteLink, and LACSLink options to produce a CASS form
PS 3553.
You can use the Use.gsd and Usw.gsd files in the Centrus Data Product installation for 135
days, but after 105 days you cannot create a CASS report.
For more information about CASS, visit the USPS National Customer Support Center
(NCSC) Website at http://ribbs.usps.gov/files/cass/, or call the NCSC at 1-800-642- 2914.
In this appendix
USPS Link products overview 489
Implementing LACSLink and DPV 493
False positive report example code 493
Reporting a false positive address 499
Understanding SuiteLINK for secondary numbers 500
USPS Link products overview
This appendix provides information on Delivery Point Validation (DPV), Locatable Address
Conversion System process (LACSLink), SuiteLink, and Residential Delivery Indicator (RDI),
available with GeoStan.
Note: GeoStan requires the DPV and LACSLink options in CASS mode to receive ZIP + 4
and ZIP + 4 related output (DPBC, USPS record type, etc.). GeoStan also requires
the DPV SuiteLink, and LACSLink options to produce a CASS form PS 3553.
DPV overview
Delivery Point Validation (DPV™) is a United States Postal Service (USPS®) technology that
validates the accuracy of address information down to the physical delivery point. DPV is
only available through a CASS-certified vendor, such as Precisely.
Previous address-matching software could only validate that an address fell within the low-
to-high address range for the named street. By incorporating the DPV technology, you can
resolve multiple matches and determine if the actual address exists. Using DPV reduces
undeliverable-as-addressed (UAA) mail that results from inaccurate addresses, reducing
postage costs and other business costs associated with inaccurate address information.
DPV also provides unique address attributes to help produce more targeted mailing lists.
For example, DPV can indicate if a location is vacant and can identify commercial mail
receiving agencies (CMRAs) and private mail boxes.
Although DPV can validate the accuracy of an existing address, you cannot use DPV to
create address lists. DPV is a secure dataset of USPS addresses. For example, you can
validate that 123 Elm Street Apartment 6 exists, but you cannot ask who lives in Apartment
6 or if there is an Apartment 7 at the same street address.
With DPV, your application automatically processes every ZIP+4 coded record against the
DPV files. Using DPV may increase your ZIP+4 match rate, but may also increase
processing time. Therefore, you may not wish to use DPV if you are not CASS certifying.
LACSLink is a secure dataset of USPS addresses. Although LACSLink can validate the
accuracy of an existing address, you cannot use LACSLink to create address lists.
Note: LACSLink is not run in multiple match searches.
DPV DPV processing was terminated due to the detection of what is determined to be
an artificially created address. No address beyond this point has been DPV
validated. In Accordance with the License Agreement between USPS and
Precisely, DPV shall be used to validate legitimately obtained addresses only,
and shall not be used for the purpose of artificially creating address lists. The
written Agreement between Precisely and the Precisely customer shall also
include the same restriction against using DPV to artificially create address lists.
Continuing use of DPV requires compliance with all terms of the License
Agreement. If you believe this address was identified in error, please contact
Precisely.
Note: Positions 156-180 in the previous table do not exist in the LACSLink false-positive
header record.
The detail record contains false positive record information.
Data expiration
The USPS has determined that the ZIP+4 Directory data, DPV data, and LACSLink data
expire in 105 days for CASS processing. The date is measured from the release of the
Postal database, which is the 15th of the month indicated on the Precisely data CD. For
example, the June data release is good for 105 days from the 15th of June. However, in
non-CASS processing modes, ZIP+4 data expires in 135 days.
RDI overview
The Residential Delivery Indicator (RDI™) is a United States Postal Service (USPS®) data
product that identifies whether a delivery type is classified as residential or business. If you
are shipping to residences, you may lower costs by shipping with the Postal Service™ and
avoid residential delivery surcharges typically charged by other shipping companies.
Note: To use RDI, DPV must also be initialized.
When you implement DPV and LACSLink you must first initialize GeoStan. After you have
initialized GeoStan, you can initialize DPV and LACSLink.
If you initialize DPV, GeoStan automatically uses DPV to resolve match candidatees. DPV
will not delivery point validate unless you specifically request DPV output. If you do not
specifically request DPV output DPV will never hit a false-positive address.
GsId gs;
GsFunStat retcode;
char buffer[GS_MAX_STR_LEN];
char buffer2[GS_MAX_STR_LEN];
FILE * DPVfalsPosOut; /* DPV false positive file pointer */
FILE * LACSfalsPosOut; /* LACSLink false positive file pointer */
GsFalsePosHeaderData FPheaderData; /* DPV/LACSLink false positive
header record */
GsFalsePosDetailData FPdetailData; /* DPV/LACSLink false positive
detail record */
char * mailerName = "Precisely";
char * mailerAddress = "4750 WALNUT ST STE 200";
char * mailerCity = "BOULDER";
char * mailerState = "CO";
char * mailerZip = "803012532";
PropList initProps;
PropList statusProps;
PropList findProps;
/* initialize GeoStan */
gs = GsInitWithProps( &initProps, &statusProps );
GsPropListWrite( &statusProps, "stdout", 0, 0 );
while ( GsErrorHas(gs) )
{
if ( gs == 0 )
{
if ( !bVal )
GsClear( gs );
GsDataSet( gs, GS_FIRM_NAME, "DIXIES DAISYS FLOWER SERVICE");
GsDataSet( gs, GS_ADDRLINE, "74203 PERRANIA");
GsDataSet( gs, GS_LASTLINE, "GRANT CO 80448");
retcode = GsFindWithProps( gs, &findProps );
/*
A DPV false positive occurred.
Write a false positive report
*/
DPVfalsPosOut = fopen("DPVfalsePos.rpt", "w");
if ( DPVfalsPosOut )
{
fclose(DPVfalsPosOut);
}
else
{
GsClear( gs );
GsDataSet( gs, GS_ADDRLINE, "RR 1 BOX 6300");
GsDataSet( gs, GS_LASTLINE, "MOUNT SIDNEY VA 24467");
retcode = GsFindWithProps( gs, &findProps );
/*
A LACSLink false positive occurred.
Write a false positive report */
LACSfalsPosOut = fopen("LACSfalsePos.rpt", "w");
if ( LACSfalsPosOut )
{
fclose(LACSfalsPosOut);
}
else
{
GsTerm( gs );
GsPropListDestroy( &findProps );
GsPropListDestroy( &initProps );
GsPropListDestroy( &statusProps );
return 0;
}
As an example, when entering the following address with SuiteLink enabled in CASS mode:
UT Animal Research
910 Madison Ave
Memphis TN 38103
Or
UT Animal Research
910 Madison Ave #823
Memphis TN 38103
If you have licensed the SuiteLink processing option, you must install the SuiteLink data and set
the SuiteLink initialization properties for GeoStan to process your address through SuiteLink.
For more information on SuiteLink enums and functions, see the following sections:
• “Enums for storing and retrieving data” on page 96 for C and page 279 for COBOL.
• GsFindWithProps properties
In this appendix
This appendix includes information on both auxiliary files and using
User Dictionaries.
User Dictionary 502
Auxiliary files 508
User Dictionary
This chapter includes information on creating User Dictionaries, source data requirements
and required fields, and other information specific to working with User Dictionaries.
Note: User Dictionaries are not for use with CASS geocoding.
• Understanding User Dictionary capabilities and requirements
• Source data requirements
• Required input fields
• Optional (recommended) input fields
• User Dictionary file names and formats
• Additional User Dictionary considerations
– Data Access License
– Use without GSD data files
– CASS standards
– Address Range Order
– Street intersections and User Dictionaries
• Using User Dictionaries with address point interpolation
• Preferring User Dictionary Matches
Maximum field
Required fields Description length
Right ZIP Code ZIP Code for the right side of the street. 5
Maximum field
Optional fields Description length
Left Odd/Even indicator* Left side of the street contains only odd 1
or even address ranges (O=odd,
E=even, B=both)
If your data includes place names, the dictionary contains the following files:
ud1.pdx
ud1.pbx
CASS standards
You cannot geocode to CASS standards using a User Dictionary. This also means that the
ParcelPrecision Dictionary cannot be used during CASS geocoding.
Example 1: Intersection in User Dictionary does not have end points for all segments.
GeoStan does not recognize this as an intersection.
Example 2: Intersection in TIGER-based GSD includes end points for all segments.
GeoStan geocodes to this intersection.
Auxiliary files
Preciselyupdates its data regularly to incorporate new rules by government entities and
enhancements by third-party data providers. In some cases, your organization may have
newer information that Precisely has not yet incorporated into the data files. Auxiliary files
provide a way for you to process your input records against a file that includes these
changes.
Record types
You can include two types of records in your auxiliary file.
Street Records
A street record contains a range of one or more addresses on
a street. To be a valid street record the record must have the
following fields:
ZIP Code
Street name
Street type abbreviation, if part of the address
Predirectional abbreviation, if part of the address
Postdirectional abbreviation, if part of the address
Low house number within the street segment
High house number within the street segment
Beginning longitude of the street segment
Beginning latitude of the street segment
During processing GeoStan ignores any record that does not comply with the preceding
requirements.
Default values
GeoStan uses the following defaults if you do not include the values in the auxiliary file:
• House number parity = B (both odds and evens)
• Segment direction = F (forward) or A (ascending), these are interchangeable.
• Side of street = U (unknown)
Matching overview
GeoStan performs the following steps when matching an input address to an auxiliary file.
1. GeoStan determines if there is an auxiliary file present.
GeoStan only accepts one auxiliary file. If more than one auxiliary files is present,
GeoStan attempts to match against the first file. GeoStan ignores any additional
auxiliary files for matching, regardless if Geostan found a match to the first auxiliary file.
If a record within the auxiliary files is invalid, GeoStan returns a message indicating the
auxiliary file has an invalid record. GeoStan continues to process input addresses
against the auxiliary file, but will not match to the invalid auxiliary file record.
2. If an auxiliary file is present, GeoStan first attempts to match to the auxiliary file.
GeoStan assumes that the auxiliary file is the most accurate data set and first attempts
to find a match to the input address in the auxiliary file. If GeoStan cannot find a match
in the auxiliary file, it continues to process as normal against the traditional GeoStan
data sets.
Note: GeoStan only matches your input address to your auxiliary file if there is an exact
match. Therefore, your input address list should be as clean as possible; free of
misspellings and incomplete addresses.
3. If GeoStan finds an exact record match to the auxiliary file, it standardizes the match to
USPS regulations and returns the output of the auxiliary file match.
Note: You cannot update the auxiliary file while GeoStan is running. If you want to
update the auxiliary file, you need to terminate GeoStan before attempting to
replace or edit the file.
GeoStan.getRange GeoStan.getRange
Segment.getCoords Segment.Coords
Required
RESERVED RESERVED 1 72
a For even and odd house number parity records, this specifies on which side of the street the house lays. For records containing
both even and odd house numbers, the odd house numbers are on the specified side of the street, and the even house
numbers are on the other side. This is a factor when using street offset.
A block assignments
(or blockface)
address elements For the assignment of ZIP + 4 codes, one
The components of a street address, side of a street, from one intersection to the
including house number, prefix direction, next.
street name, street type, and postfix
C
direction. These elements are parsed by
GeoStan and should not be entered
carrier route
separately.
The addresses to which a carrier delivers
address geocoding mail. In common usage, a carrier route
See geocode, geocoding. includes city routes, rural routes, highway
address standardization contract routes, post office box sections, and
general delivery units.
Address standardization is the process of
taking an address and verifying that each CASS
component meets U.S. Postal Service Coding Accuracy Support System. A service
guidelines for addresses. For example, offered to mailers, service bureaus, and
when properly abbreviated, “123 Main software vendors that improves the
Avenue” appears as “123 Main Ave.” During accuracy of delivery point codes, ZIP + 4
standardization, minor misspellings, codes, 5-digit ZIP Codes, and carrier route
dropped address elements, and information on mail. CASS provides a
abbreviations are corrected and the correct common platform to measure the quality of
city, state, and ZIP Code are provided. address matching software and useful
alias diagnostics to correct software problems.
A recognized alternate for a street name CBSA
maintained by association in the database. A statistical geographic entity consisting of
alias information the county or counties associated with at
least one core (urbanized area or urban
Data returned with certain enums when it
cluster) of at least 10,000 population, plus
exists. Not returned by all enums even if
adjacent counties having a high degree of
specifically requested.
social and economic integration with the
alternate record core as measured through commuting ties
Additional or differing information that may with the counties containing the core.
be available about a specific address but Metropolitan and Micropolitan Statistical
that differs from the base record. See the Areas are the two categories of Core Based
enums table for necessary flag settings. Statistical Areas.
B CBSA Division
A subdivision of CBSA.
base record Census block ID
The principle, rather than an alternate, The 15-digit identification number used to
record within the database. specify a particular aggregate or block of
addresses associated through census
processes.
E
eLOT
The Enhanced Line of Travel (eLOT) Product was developed to provide mailers the ability to sort
their mailings in approximate carrier-casing sequence. To aid in mail sorting, eLOT contains an
eLOT sequence number field and an ascending/descending code. The eLOT sequence number
indicates the first occurrence of delivery made to the add-on range within the carrier route, and
the ascending/descending code indicates the approximate delivery order within the sequence
number. Mailers can use eLOT processing to qualify for enhanced carrier route presort
discounts.
F
Finance Area
A Finance Area is an area defined by the U.S. Postal Service from which it collects cost and
statistical data. A Finance Area is frequently used for area searches, since it covers some or all
of the ZIP Code areas in a town or city.
finance number
An assigned six-digit number that identifies and installation for processing it’s financial data. The
first two digits are the state code and the next four are uniquely assigned from 0001 through 9999
to each installation in alphabetical order.
FIPS code
Federal Information Processing Standards code. A FIPS Code, also called a Census ID, uniquely
identifies each piece of Census geography. The syntax of the FIPS code is as follows:
G
GDT
Geographic Data Technology data. Produced by TomTom, a premium vendor of street segment
files.
geocode, geocoding
A geocode is the geographic information associated with a unique address or centroid, such as
longitude and latitude. Geocoding is the process of assigning data based upon location
information. GeoStan uses an address or ZIP Code to assign latitude, longitude, and Census
FIPS information.
GIS
Geographic Information System. A computer-based tool for enhancing geographic data by
analyzing both the physical location in space and the set of characteristics associated with a
location.
GSD files
GeoStan directory files.
GsEnums
Enumerated types in the GeoStan API. These enums are prefixed with “GS_” and are defined in
the geostan.h file.
GSL file
USPS eLOT and Z4Change data. This files is used to assign line of travel (LOT) codes to
addresses.
GSU files
GSU files contain information to match addresses based on unique ZIP Code and additional
highrise unit information.
GSX files
Geographic spatial index. These files are used by spatial functions and reverse geocoding in
GeoStan.
GSZ file
GeoStan ZIPMove file contains USPS ZIPMove data.
I
intersection matches
Intersections matches are indicated by an x___ match code. For example, 28th Street and
Valmont intersections may be standardized and geocoded and return demographic information.
Intersections do not represent a valid address for mailings.
L
LACS
Locatable Address Conversion System. This system corrects addresses electronically for areas
that have undergone permanent address conversions. The address conversion occurred as a
result of the 911 system implementation and involves renumbering and renaming rural route and
highway contract route information as city-style addresses with street number and name.
lat/lon; latitude/longitude coordinates
Longitude and latitude coordinates are always in degrees, and are always represented as 64-bit
doubles. Positive numbers represent the Eastern and Northern hemispheres, respectively, and
negative numbers represent the Western and Southern hemispheres. For example, the point
140W by 30N would be represented as –140.0,30.0. The library always assumes that the
longitude coordinate is the horizontal direction and the latitude coordinate is the vertical direction.
Support is not provided for user coordinates.
location code
Location codes indicate the accuracy of the assigned geocode.
M
mail stop designator
This designator indicates a routing code used by a company for internal mail delivery.
MASS
Multiline (OCR) Accuracy Support System. A tool similar to Coding Accuracy Support System
(CASS) that accesses and checks the address matching software used by customers’ multiline
optical character readers (OCRs).
match code
Indicates the portions of the address that matched or did not match with the address information
in the GeoStan data files.
N
NAD
The North American Datum (NAD) is the official reference ellipsoid used for the primary geodetic
network in North America.
NAD27
NAD27 has its origin at Meades Ranch, Kansas. NAD27 does not include the Alaskan islands
and Hawaii. Latitudes and longitudes that are surveyed in the NAD27 system are valid only in
reference to NAD27 and do not tie to any maps outside the U.S.
NAD83
NAD83 is earth-centered and defined with satellite and terrestrial data. NAD83 is compatible with
the World Geodetic System 1984 (WGS84), the terrestrial reference frame associated with the
NAVSTAR Global Positioning System (GPS) now used extensively for navigation and surveying.
Note that TomTom uses WGS84 instead of NAD83. These two coordinate systems are
compatible.
O
object
A basic functional unit of a library. A library contains functions that allow the user to create,
manipulate, and destroy objects. C programmers access objects through handles that are
provided through object creation functions.
P
postdirectional (postdir)
See directionals.
predirectional (predir)
See directionals.
R
record matching algorithm
Programmed logic that allows evaluation of the results of all field matching algorithms to
determine whether two records match (i.e., are duplicates).
road class code
A key in the street segment file that identifies a road as major or minor according to the Census
Feature Classification Code.
RR
Rural Route. A delivery route served by a rural carrier.
S
soundex algorithm
A type of field matching algorithm that compares two fields based on their pronunciation.
soundex key
Generated by the GsSoundex function. Used to search the database by employing a soundex
algorithm.
spatial query functions
Used to extract data from the GSD files. These functions specify the area to be searched through
a minimum bounding rectangle rather than through city/state/ZIP or finance area.
stage 1 file
A sample address file provided by the U.S.P.S to determine if software/hardware meets postal
requirements for CASS.
T
TomTom
A premium data vendor of street segment files (previously known as TeleAtlas).
TIGER files
Topographically Integrated Geographic Encoding and Referencing. A digital database of
geographic features created by the US Geological Survey (USGS), covering the entire United
States.
TLID
TIGER/Line® Identification Number.
The TIGER/Line® files use a permanent 10-digit TLID to uniquely identify a complete chain for
the Nation. The 10-digit TLID will not exceed the value 231-1 (2,147,483,647) and represents the
same complete chain in all versions of this file, beginning with the TIGER/Line® Precensus Files,
1990. The minimum value is 100,001. Topological changes to the complete chain causes the
TLIDs to change. For instance, when updates split an existing complete chain, each of the new
parts receives a new TLID; the old TLID is not reused.
As distributed, TIGER/Line® files are grouped by county (or statistically equivalent entity). A
complete chain representing a segment of the boundary between two neighboring counties may
have the same TLID code in both counties or it may have different TLID codes even though the
complete chain represents the exact same feature on the ground.
U
unit designator
Indicates the type of unit (e.g., apartment, unit).
USPS data files
Files provided by the post office containing address and ZIP Code information.
Z
ZIP + 4 directory file
Address records that contain the ZIP + 4 codes for all delivery points, in an electronic form.
ZIP + 4 centroid geocoding
See geocoding.
T
Third hex position 469
Two-line 41
Two-line matching 27
U
User Dictionary
Address point interpolation 56
Functions
GsGetDBMetadata 212
precisely.com