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
GsIdgs ID returned by GsInitWithProps() for the current instance of GeoStan. Input.
GsGeoStructEx*pGeoStruct Pointer to the GsGeoStruct containing the input and output fields for this API. Input, Output.
inCity City for which to search. Input.
inCounty County for which to search. Input.
inState State for which to search. Input.
outCity Output city. Output.
outCountry Output county. Output.
outState Output state. Output.
outLat Returned latitude of the geographic centroid. Output.
outLong Returned longitude of the geographic centroid. Output.
outRank Returned geographic rank of the city for city centroid. Output.
outResultCode Result code equivalent (G3 - city centroid, G2 - country centroid, G1 - state centroid). Output.
outLocCode Location code equivalent (GM - city, GC - county, GS - state). Output.
inGeoLibVer GeoStan version. Input.
outClose True indicates a close match. Output.
outFipsCode FIPS Code. 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
To use this API, you will use the following structure defined in geostan.h.
/* The Geographic query structure. */
typedef struct GsGeoStructEx
{
char inCity[GS_CITY_CCS_LENGTH]; /* input city */
char inCounty[GS_COUNTY_CCS_LENGTH]; /* input county */
char inState[GS_STATE_CCS_LENGTH]; /* input state */
char outCity[GS_CITY_CCS_LENGTH]; /* output city */
char outCounty[GS_COUNTY_CCS_LENGTH]; /* output county */
char outState[GS_STATE_CCS_LENGTH]; /* output state */
char outLat[GS_LAT_LENGTH]; /* output latitude */
char outLong[GS_LON_LENGTH]; /* output longitude */
char outRank[GS_RANK_LENGTH]; /* output geographic rank */
char outResultCode[GS_MM_RESULT_CODE_LENGTH ]; /* output result code */
char outLocCode[GS_LOC_CODE_LENGTH]; /* output location code */
char outClose; /* output close match flag */
long inGeoLibVer; /* geostan version */
char outFipsCode[GS_FIPS_CCS_LENGTH]; /* output fips code */
}
GsGeoStructEx;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;
printf("Enter City : ");
gets(p.inCity);
printf("Enter County : ");
gets(p.inCounty);
printf("Enter State : ");
gets(p.inState);
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");
}
}
}
}