synopsis.
the geo subroutines here all require a dbconnection_o that has been set up to access a database. Most follow a convention of setting up input parameters in an input parameter namevalue_set_o and return the results in an output parameter namevalue_set_o. A few take a planet_coord_o as input, in addition to a dbconnection_o handle.

[C] functions (aka subroutines):

zgeo_iscountry_valid()
SIGNATURE: boolean zgeo_iscountry_valid (const string_o &s, int *pi = NULL)
SYNOPSIS:
looks up the name given in 's' in the "country" table to see if the name represents a valid country. 's' can also be a 2-letter ISO country code.
PARAMETERS

• s: [input] the name of the country to validate. This value can be the name, or the 2-letter [ISO] country code.
• pi: [output] error indicator parameter. values:
  0: successfully executed
  zErr_Param_NotSet: 'nam' is an empty string
  zErr_Data_Corrupted: more than 1 country matched 'nam' (impossible - this should never happen, indicating that the database is corrupted)
  zErr_DB_Cannot_Open: cannot access the database
  zErr_NotInitialized: internal error (shouldn't happen)

DESCRIPTION:
WARNING: this function is highly dependent on the assumption that your application has opened the database containing Z Directory "geo" tables and can access them. If the geo tables are in a database other than the default, currently open database (that is, opened by a Z Directory dbconnection object), this routine will fail.
If more control is required for accessing the database, use zgeo_country_info(), or the version of zgeo_iscountry_valid() with a dbconnection_o parameter in its argument list.
RETURNS:
TRUE: 's' is a valid country name or code;
FALSE: 's' is not a valid country name, or an error occurred
 

zgeo_iscountry_valid()
SIGNATURE: boolean zgeo_iscountry_valid (dbconnection_o &dbx, const string_o &s, int *pi = NULL)
SYNOPSIS:
looks up the name given in 's' in the "country" table to see if the name represents a valid country. 's' can also be a 2-letter ISO country code.
PARAMETERS

• dbx: [input] a (reference) handle a dbconnection object that accesses the geo database. This object need not be open, but the parameters for accessing the database (server and database name, account, password, etc) must be set in advance.
• s: [input] the name of the country to validate. This value can be the name, or the 2-letter [ISO] country code.
• pi: [output] error indicator parameter. values:
  0: successfully executed
  zErr_Param_NotSet: 'nam' is an empty string
  zErr_Data_Corrupted: more than 1 country matched 'nam' (impossible - this should never happen, indicating that the database is corrupted)
  zErr_DB_Cannot_Open: cannot access the database
  zErr_NotInitialized: internal error (shouldn't happen)

DESCRIPTION:
this subrouine has a sibling with the same name. The only difference between these two routines is that this subroutine includes the 'dbx' [first] parameter argument, allowing more specific control of which database is to be used for accessing the "geo" data.
This subroutine is the recommended one to use, as it is common for applications to have a 2 or more databases open via the dbconnection object. The geo data can (and often is) in a separate database. In this case, using zgeo_iscountry_valid() without specifying the underlying database (iva 'dbx') can cause the other routine to fail.
RETURNS:
TRUE: 's' is a valid country name or code;
FALSE: 's' is not a valid country name, or an error occurred
 

z_IP_to_latlong()
SIGNATURE: int z_IP_to_latlong (const internet_address_o &ip, const string_o &skey, namevalue_set_o &nvs, int *pi = NULL)
SYNOPSIS:
this looks up the IP address specified by 'ip' and maps it to a latitude and longitude point. Additional data may be provided. The results are put into output parameter 'nvs'.
PARAMETERS

• ip: [input] the IP address to look up
• skey: [input] unused
• nvs: the output, as a list of name-value pairs
• pi: [output] error indicator parameter. values:
  0: all ok, data retrieved
  zErr_NotFound: lookup failed
  zErr_NoData: response message was 0-length
  zErr_AccessDenied: response returned ERROR
  zGEOErr_LatLonWeb_BadAck: bad response code; neither ERROR, OK
  zGEOErr_LatLonWeb_GPFail: general failure

DESCRIPTION:
The function requires just setting an IP address into input parameter 'ip'. The string 'skey' is reserved, and currently can have any value. The following keys are used for 'nvs':
IP: the inputted IP address, as a string
country: The country the IP address falls into
country_name: usually the same value as "country"
region_name: any region (state or other 2nd-level subdivision)
city_name: any corresponding city found for the IP address
post_code: postal (zip) code, if applicable
latitude: IP address latitude
longitude: IP address longiitude
timezone: time zone designator for the (lat-lon) point
RETURNS:
0: success
-1: error
[n >= 1]: error; # of errors that occured
TRAITS:
This function requires an internet connection, uses an external 3rd-party service, and because of this implementation, the results are not guaranteed and this should be considered to be an unstable function.
 

z_IP_to_latlong_via_ipinfodb_com()
SIGNATURE: int z_IP_to_latlong_via_ipinfodb_com (const internet_address_o &ip, const string_o &skey, namevalue_set_o &nvs, int *pi = NULL)
SYNOPSIS:
this is basically the same as z_IP_to_latlong(), only a specific implementation of it. This function is identical in parameters and input-output behaviour as that function [which see]. It is not intended for public use. Use at your own risk.
TRAITS: this function will probably go away soon.
 

zgeo_city_info()
SIGNATURE: int zgeo_city_info (dbconnection_o &dbx, const string_o &ci, const string_o &co, namevalue_set_o &nvs, boolean use_codeonly = TRUE, int *pi = NULL)
SYNOPSIS: this function looks up a city given by the city 'ci' and country 'co'.
PARAMETERS

• dbx: a handle to a dbconnection object. This object must be preconfigured with an existing, opened database in order for this subroutine to succeed.
• ci: name of the city to look up.
• co: name of the country that the city is in [required].
• nvs: output name-value list. the applicable keys are:
  ID_geo: the internal database ID for this item
  country
  lm_class
  lm_code
  name
  elevation
  population
  latitude
  longitude
  govcode1
  govcode2
  govcode3
  govcode4
• pi: [output] error indicator parameter. values:
  zGEOErr_DB_Exec: error in database execution
  zErr_NoData: nothing found
  zErr_Result_TooBig: more than one result found
  zGEOErr_DB_CantFetch: problem in retrieving data
  zGEOErr_DB_Strange: other database-related error

DESCRIPTION:
this function is analogous in use and conventions to 'zgeo_country_info()'. It requires an exact match of city and country name.
RETURNS:
0: success
1: not found
-1: error - failure
 

zgeo_country_info()
SIGNATURE: int zgeo_country_info (dbconnection_o &dbx, const string_o &co, namevalue_set_o &nvs, boolean use_codeonly = FALSE, int *pi = NULL)
SYNOPSIS: fetches information about the country specified by parameter 'co'. Results are put into 'nvs' as name-value pairs.
PARAMETERS

• dbx: a handle to a dbconnection object. This object must be preconfigured with an existing, opened database in order for this subroutine to succeed.
• co: name of the country that the city is in [required].
• nvs: output name-value list. the applicable keys are, with their corresponding DB table columns:
  ID_geo .......: country.id_geo
  code .........: country.code
  continent ....: country.continent
  owner_code ...: country.owner
  name .........: country.name
  capital ......: country.capital
  area .........: country.area
  population ...: country.population
  TLD ..........: country.TLD
  phone_code ...: country.phone_code
  money_code ...: country.money_code
  money_name ...: country.money_name
  abbreviation .: country.abbrev
  neighbor_list : country.neighbors
  nameserver ...: country.nameserver
  net_codes ....: country.net_codes
  language_list : country.languages
• use_codeonly: the 4th parameter, with this rather long name, is TRUE if the value supplied in 'cc' is the 2-letter [ISO] country code, and you are sure of that. Leave it at the default value of FALSE if 'cc' is the country's name (and/or country code).

DESCRIPTION:
see the analogous function zgeo_city_info() for more information about the how to use this function. Some valuable hints about the search for the country name: If 'use_codeonly' is FALSE, the country name must match exactly (caes is not relevant, as per SQL rules - however, this fact may depend on your database and its settings). This subroutine makes up to 4 iterations trying to find the given country. it will look at all "name" type fields: "name", "full_name", "alt_name " (and "code") to try to find a match.
 

zgeo_postal_info()
SIGNATURE: int zgeo_postal_info (dbconnection_o &dbx, const namevalue_set_o &nvi, namevalue_set_o &nvs, int *pi = NULL)
SYNOPSIS: this retrieves a list of up to 5 of the closest post offices to a given latitude-longitude, specified in 'nvi'.
DESCRIPTION:
Here is an example of how to use this:

dbconnection_o dbx;
namevalue_set_o nvs, nvo;
string_o s0val, s0nam, s1val, s1nam;
// --configure 'dbx' and open the database--
nvs.load ("latitude=\"33.5\";longitude=122;country=Angola");
zgeo_postal_info(dbx, nvs, nvo);


s0val = z_value_from_nvset("post0_value", nvo);
s0nam = z_value_from_nvset("post0_name",  nvo);
s1val = z_value_from_nvset("post1_value", nvo);


std::cout << "1st zip code: " << s0val << std::endl;
std::cout << "1st post office name: " << s0nam << std::endl;
std::cout << "2nd zip code: " << s1val << std::endl;

TRAITS: This is a somewhat database-intensive operation
 

zgeo_city_info()
SIGNATURE: int zgeo_city_info (dbconnection_o &dbx, const namevalue_set_o &nvi, namevalue_set_o &nvs, const count_t, int *pi = NULL)
SYNOPSIS:
this fetches up to 8 cities that are closest to a specific latitude-longitude point (specified in 'nvi'). This function is a thin wrapper around zgeo_landmark_info(), so its conventions and behaviours are identical to that function.
DESCRIPTION:
3 input variables (in "nvi') are required: "latitude", "longitude", and "country". The output is put into 'nvs', and the format is markedly different from other geo functions: the output data block is converted to a matrix databag, which is then converted to a "hexadecimal" string (see z_str_to_hex()). The columns of this matrix databag is given by the macro 'zGEO_CityList_Cols' (in z_geo.h).
 

zgeo_landmark_info()
SIGNATURE: int zgeo_landmark_info (dbconnection_o &dbx, const namevalue_set_o &nvi, namevalue_set_o &nvs, const count_t, int *pi = NULL)
SYNOPSIS: this returns up to the nearest 50 landmarks for a given lat-lon coordinate.
DESCRIPTION:
3 input variables (in "nvi') are required: "latitude", "longitude", and "country". The output is put into 'nvs', and the format is markedly different from other geo functions: the output data block is converted to a matrix databag, which is then converted to a "hexadecimal" string (see z_str_to_hex()). The columns of this matrix databag is given by the macro 'zGEO_LandmarkList_Cols' (in z_geo.h).
 

zgeo_closest_country()
SIGNATURE: string_o zgeo_closest_country (dbconnection_o &dbx, const planet_coord_o &point, int *pi = NULL)
SYNOPSIS:
given a world co-ordinate point 'point', this subroutine attempts to find a suitable country that contains the point. This routine is a wrapper around zgeo_countries_bboxgot(). It is computationally expensive. If the point falls outside a country (eg over an ocean), this may fail to retrieve a nearest country.
DESCRIPTION:
this routine uses east-west-north-south "bounding boxes" that contain a given country. If a point falls within a country's bounding box, but is outside the country, it may be considered to be "in" that country.
 

zgeo_countries_bboxgot()
SIGNATURE: int zgeo_countries_bboxgot (dbconnection_o &dbx, const planet_coord_o &point, vset_o<string_o> &clist, int *pi = NULL)
SYNOPSIS:
this returns a list of countries (in output container variable 'clist') whose bounding boxes contain the co-ordinate specified by 'point'. There may be multiple countries for a given point for a couple of different reasons: some countries (such as England and France) own territories that are very far away, resulting in huge, impractical bounding boxes that can cover the entire planet; or a country may stake a claim to a piece of Antarctica, expanding its bounding box to there; or, the country may be oddly shaped - skewed diagonally or curving around, making its bounding box overlap that of other countries.
TRAITS: this is a computationally expensive function call
 

zgeo_landmark_classcode_to_name()
SIGNATURE: string_o zgeo_landmark_classcode_to_name (const string_o &group, const string_o &code, int *pi = NULL)
SYNOPSIS:
this subroutine maps a landmark group and code to its "display name". These fields are stored in an array of 'geo_lmcode' record structures. The group and code are geonames labels.
PARAMETERS

• group: 1-letter group code. Values are:
  A: country, state, region, ...
  H: stream, lake, ...
  L: parks, area, ...
  P: city, village,...
  R: road, railroad
  S: spot, building, farm
  T: mountain, hill, rock, ...
  U: under water item
  V: forest, heath, ...
• code: [2-5 letter] geonames code
• pi: [output] error indicator parameter. values:
  0: all ok, item retrieved
  zErr_Param_BadVal: illegal group code
  zErr_NoMatch: no matching entry for the given group + code

DESCRIPTION:
Example:
zgeo_landmark_classcode_to_name ("A", "ADMD")
returns "gov't admin zone";
zgeo_landmark_classcode_to_name ("L", "NVB")
returns "naval base";
zgeo_landmark_classcode_to_name ("V", "FRSTF")
returns "fossilized forest".
 

zgeo_name_to_sex()
SIGNATURE: char zgeo_name_to_sex (dbconnection_o &dbx, const string_o &nam, int *pi = NULL)
SYNOPSIS:
this subroutine returns a single-character code representing the sex assigned for the name specified by 'nam'. The possible values are:

• M - male
• F - female
• B - both sexes (either)
• N - needs to be researched
• ? - not found (or error)

PARAMETERS

• dbx: a handle to a dbconnection object. This object must be preconfigured with an existing, opened database in order for this subroutine to succeed.
• nam: the name (person's first name) to search for.
• pi: [output] error indicator parameter. values:
  zGEOErr_DB_Exec: database error
  zGEOErr_DB_CantFetch: database error
  zGEOErr_DB_Strange: database error
  zErr_NoMatch: the name was not found

RETURNS:
'M', 'F', or 'B' (other(s) - 'N'): the associated sex. M: male; F: female; B: both (can be male or female); N: apparently not a name, but this needs to be confirmed
'?': either the name was not found, or other error occurred (see value of error variable 'pi')
 

note.
many of these routines are computationally expensive, and should be used sparingly.