Top

geodata.Geodata module

Provides a placename lookup gazeteer based on placename data from geonames.org.
Provides the location lookup methods for the geodata package.

  • Creates a local sqlite3 place database of geonames.org data
  • Parses lookup text and returns multiple matches ranked by closeness to lookup term
  • Provides latitude/longitude
  • Supports Wildcard search, Phonetic/Soundex search, and Word search of place names
  • Provides search by feature type (e.g. mountain, cemetery, palace, etc)
  • Database can be filtered to only include specified countries, languages, and feature types

Main routines for Geodata package:
example.py - a sample demonstrating place lookups using geodata
geodata.open - opens the database. creates the database if missing
geodata.find_best_match - provides the best match for the requested location name
geodata.find_matches - provides a ranked list of matches for the requested location name
geodata.find_feature - provides a lookup by feature type and returns a ranked list of matches
normalize.py - Attempts to normalize text into streetname, town, county, state, country

Module variables

var admin1_name_start_year

var country_name_start_year

var default

var feature_priority

Classes

class Geodata

Provide a place lookup gazeteer based on data from geonames.org

Ancestors (in MRO)

Static methods

def __init__(

self, directory_name, display_progress, show_message, exit_on_error, languages_list_dct, feature_code_list_dct, supported_countries_dct)

Init

Args:

directory_name: directory where geoname.org files are.  DB will be in 'cache' folder under this   
display_progress: None or function to display progress(percent_done:int, msg:str)  
show_message: If True - show TKInter message dialog on error   
exit_on_error: If True - exit on significant error   
languages_list_dct: Dictionary of ISO-2 languages to import from AlternateNamesV2.txt   
feature_code_list_dct: Dictionary of Geoname Feature codes to import into DB   
supported_countries_dct: Dictionary of ISO-2 Country codes to import into DB

def close(

self)

Close files and database

Returns: None

def close_diag_file(

self)

Close diagnostic file

Returns:

def distance(

lat_a, lon_a, lat_b, lon_b)

Returns rectilinear distance in degrees between two lat/longs
Args:
lat_a: latitude of point A
lon_a: longitude of point A
lat_b: latitude of point B
lon_b: longitude of point B
Returns: Rectilinear distance between two points

def filter_results(

self, place)

Sort place.georow_list by match score and eliminate duplicates

In case of duplicate, keep the one with best match score.
See MatchScore.match_score() for details on score calculation
Discard names that didnt exist at time of event (update result flag if this occurs)
Duplicates are defined as two items with:
1) same GEOID or 2) same name and similar lat/lon (within Rectilinear Distance of distance_cutoff degrees)

Add flag if we hit the lookup limit

Args:

place:

Returns:

ResultFlags(limited=limited_flag, filtered=date_filtered)

def find_best_match(

self, location, place)

Find the best scoring match for this location in the geoname dictionary.

Args:

location:  location name, e.g. Los Angeles, California, USA   
place:  Loc instance

Returns: None

place is updated with -- lat, lon, district, city, country_iso, result code

def find_feature(

self, place)

Lookup location with - name, country, and feature

Args:

place: place.name, place.country, and place.feature are used for lookup

Returns:

None.  place.georow_list contains matches

def find_geoid(

self, geoid, place)

Lookup by geoid

Args:

geoid:  Geonames.org geoid
place:  Location fields in place are updated

Returns: None. Location fields in Loc are updated

def find_matches(

self, location, place, plain_search)

Find a location in the geoname database. On successful match, place.georow_list will contain
list of georows that matched the name. Each georow can be copied to a Loc structure by
calling process_result

Args:

location: comma separated name of location to find, e.g. 'Los Angeles, California, USA'   
place: Loc structure   
plain_search: If True then don't do wildcard searches

Returns:

GeoUtil.Result code

def is_country_valid(

self, place)

See if COUNTRY is present and is in the supported country list

Args:

place:

Returns:

True if country is valid

def log_results(

self, geo_row_list)

def open(

self, repair_database, query_limit)

Open geodb. Create DB if needed

Args:

repair_database: If True, create DB if missing or damaged. 
query_limit:  SQL query limit

Returns:

True if error

def open_diag_file(

self, miss_diag_fname)

Open diagnostic file

Args:

miss_diag_fname:

Returns:

def process_results(

self, place, flags)

Update fields in place record using first entry in place.georow_list
Updates fields with available data: city, admin1, admin2, country, lat/long, feature, etc.

Args:

place: Loc instance   
flags: Flags tuple as returned by sort_results

Returns:

None.  place instance fields are updated

Instance variables

var display_progress

var distance_cutoff

var geo_build

var logger

var miss_diag_file

class ResultFlags

ResultFlags(limited, filtered)

Ancestors (in MRO)

Instance variables

var filtered

Alias for field number 1

var limited

Alias for field number 0