header file(s): z_geo.h

synopsis.
The geographical functions provide current information about items on this planet from the human perspective: cities, countries, postal (USA: "zip") codes, and landmarks. A "landmark" is a generic label for a thing on the surface of Earth. It can be a river, a building, a city, a street, a golf course, or many other things. All the functions work in a similar fashion. The data for these things must be loaded into a database in order for the functions to work successfully. Your application can mix and match databases; say you are using database A and the geo data reside in databaase B. Both can be accessed concurrently from the application. Each geo function takes a.dbconnection_o object, which you need to preconfigure prior to calling the geo function.

zgeo_name_to_sex() is also part of the "geo" group. This looks up a table of names for a person, and returns a code indicating the sex associated with the name ('M', 'F', 'B' - both, or '?' - not found). Although not directly an earth-bound function, the corresponding table is part of the topology database.

classes in this group: planet_coord_o

function groups:
                              layer 11 functions group

description.
The geo functions include: zgeo_iscountry_valid(name) - validates whether the country given by "name" is a valid country name.

z_IP_to_latlong(ip) - maps the given IP address (in 'ip') to a latitude-longitude point. This routine is requires an internet connection, is dependent on an external web site, and its usage is risky.

zgeo_city_info() - this takes a city name and a country name and returns various statistics about the city (if found). Data includes elevation, population, latitude, longitude, and related governmental codes.

zgeo_country_info() - for a specified country, this returns a list of information about the country: its continent, whether it is "owned" by another country, capital, area, population, TLD, phone code, money used, abbreviation, a list of neighbors, and more.

zgeo_postal_info() - For a given country, latitude, and longitude, this returns a list of nearest post-code zones.

zgeo_city_info() - This takes a country code, latitude, and longitude, and returns a list of closest. The information related to the cities includes name, latitude, longitude, elevation, and time_zone.

zgeo_landmark_info() - This takes a country code, latitude, and longitude, and returns a list of landmarks. The information related to the landmarks includes name, latitude, longitude, elevation, time_zone and other things.

zgeo_closest_country() - given a latitude-longitude point (type planet_coord_o), this routine provides a best-guess country that is "closest" to the point. The routine attempts to determine the country centroid that is closest to the point.

zgeo_countries_bboxgot() - this creaates a set of strings representing the countries whose bounding boxes contain the latitude-longitude point given as input to this subroutine.

zgeo_landmark_classcode_to_name() -

zgeo_name_to_sex() - M/F sex lookup for a name.

zgeo_name_to_sex(dbx, "John");       // returns 'M'
zgeo_name_to_sex(dbx, "Veronica");   // returns 'F'
zgeo_name_to_sex(dbx, "Terry");      // returns 'B'

examples.
Here is an example showing basic set-up and usage of the geo functions, including the planet_coord_o class. Most of the geo functions follow the same conventions.

#include "stdafx.h"
#include "z_geo.h"

void SHOW (const string_o &, const string_o &, const namevalue_set_o &);

int main (int argc, char *argv[])
{
    int ie0;
    dbconnection_o dbx;                 // a handle to the database

    dbx.set_access_method (zstyle_DBax_ADO, &ie0);
    dbx.open("localhost", "GEO_DATABASE", "sa", "MY_PASSWD", &ie0);

    planet_coord_o here;
    here.set_coords (40.714, -74);      // NYC
    string_o s = zgeo_closest_country (dbx, here,  &ie0);
    if (!ie0)
    {
        namevalue_set_o data;
        std::cout << "the closest city to (40.714, -74) is: "<< s << std::endl;
        zgeo_city_info (dbx, s, "America", data);
        SHOW (s, "population", data);           // display city's population
        SHOW (s, "elevation",  data);           // display city's elevation
        SHOW (s, "govcode1",   data);           // display gov't zone code 1
        SHOW (s, "govcode2",   data);           // display gov't zone code 2
    }
    else
        std::cout << "(40.714, -74): no city found.\n";
    return 0;
}

void SHOW (const string_o &city, const string_o &x, const namevalue_set_o &dat)
{
    std::cout << city << ": " << x << ": ";
    std::cout << z_value_from_nvset(x, dat) << std::endl;
}