com.bericotech.clavin.gazetteer

Class GeoName

java.lang.Object

com.bericotech.clavin.gazetteer.GeoName

public class GeoName
extends Object

Data-rich representation of a named location, based on entries in the GeoNames gazetteer. TODO: link administrative subdivision code fields to the GeoName records they reference

Field Summary

Fields

Modifier and Type	Field and Description
static int	OUT_OF_BOUNDS

Constructor Summary

Constructors

Constructor and Description

GeoName(int geonameID, String name, String asciiName, List<String> alternateNames, String preferredName, Double latitude, Double longitude, FeatureClass featureClass, FeatureCode featureCode, CountryCode primaryCountryCode, List<CountryCode> alternateCountryCodes, String admin1Code, String admin2Code, String admin3Code, String admin4Code, Long population, Integer elevation, Integer digitalElevationModel, TimeZone timezone, Date modificationDate, String gazetteerRecord) Sole constructor for GeoName class.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(Object obj)
String	getAdmin1Code() Get the code for the first level administrative division (e.g.
String	getAdmin2Code() Get the code for the second level administrative division (e.g.
String	getAdmin3Code() Get the code for the third level administrative division.
String	getAdmin4Code() Get the code for the fourth level administrative division.
List<CountryCode>	getAlternateCountryCodes() Get the alternate ISO-3166 2-letter country codes.
List<String>	getAlternateNames() Get the alternate names for the location.
String	getAncestryKey() Get the ancestry key that can be used to identify this administrative division.
String	getAsciiName() Get the name of the geographical point in plain ascii characters.
int	getDigitalElevationModel() Get the digital elevation model, srtm3 or gtopo30, average elevation of 3''x3'' (ca 90mx90m) or 30''x30'' (ca 900mx900m) area in meters, integer.
int	getElevation() Get the elevation in meters.
FeatureClass	getFeatureClass() Get the major feature category.
FeatureCode	getFeatureCode() Get the feature code.
String	getGazetteerRecord() Get the gazetteer record for this GeoName.
String	getGazetteerRecordWithAncestry() Get the gazetteer records for this GeoName and its ancestors, separated by newline characters.
int	getGeonameID() Get the ID of the record in geonames database.
double	getLatitude() Get the latitude in decimal degrees.
double	getLongitude() Get the longitude in decimal degrees.
Date	getModificationDate() Get the last modification date in the GeoNames database.
String	getName() Get the name of the geographical point (UTF-8).
GeoName	getParent() Get the parent of this GeoName.
String	getParentAncestryKey() Get the ancestry key that can be used to identify the direct administrative parent of this GeoName.
long	getPopulation() Get the total number of inhabitants.
String	getPreferredName() Gets the preferred name of this GeoName, if configured, otherwise returns the name.
CountryCode	getPrimaryCountryCode() Get the primary ISO-3166 2-letter country code.
String	getPrimaryCountryName()
TimeZone	getTimezone() Get the time zone for the geographical point.
int	hashCode()
boolean	isAncestorOf(GeoName geoname) Is this GeoName an ancestor of the provided GeoName?
boolean	isAncestryResolved() Check to see if the ancestry hierarchy has been completely resolved for this GeoName.
boolean	isDescendantOf(GeoName geoname) Is this GeoName a descendant of the provided GeoName?
boolean	isTopLevelAdminDivision() Is this GeoName a top-level administrative division (e.g.
boolean	isTopLevelTerritory() Is this GeoName a top-level territory? A GeoName is considered to be a top-level territory if it is an A:TERR record and the name assigned to its primary country code is either the name of the GeoName or one of its configured alternate names.
static GeoName	parseFromGeoNamesRecord(String inputLine) Builds a GeoName object based on a single gazetteer record in the GeoNames geographical database.
static GeoName	parseFromGeoNamesRecord(String inputLine, String preferredName) Builds a GeoName object based on a single gazetteer record in the GeoNames geographical database.
boolean	setParent(GeoName prnt) Set the parent of this GeoName.
String	toString() For pretty-printing.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

OUT_OF_BOUNDS

public static final int OUT_OF_BOUNDS

See Also:

Constant Field Values

Constructor Detail

GeoName

public GeoName(int geonameID,
       String name,
       String asciiName,
       List<String> alternateNames,
       String preferredName,
       Double latitude,
       Double longitude,
       FeatureClass featureClass,
       FeatureCode featureCode,
       CountryCode primaryCountryCode,
       List<CountryCode> alternateCountryCodes,
       String admin1Code,
       String admin2Code,
       String admin3Code,
       String admin4Code,
       Long population,
       Integer elevation,
       Integer digitalElevationModel,
       TimeZone timezone,
       Date modificationDate,
       String gazetteerRecord)

Sole constructor for GeoName class. Encapsulates a gazetteer record from the GeoNames database.

Parameters:

geonameID - unique identifier

name - name of this location

asciiName - plain text version of name

alternateNames - list of alternate names, if any

preferredName - the preferred name, if known

latitude - lat coord

longitude - lon coord

featureClass - general type of feature (e.g., "Populated place")

featureCode - specific type of feature (e.g., "capital of a political entity")

primaryCountryCode - ISO country code

alternateCountryCodes - list of alternate country codes, if any (i.e., disputed territories)

admin1Code - FIPS code for first-level administrative subdivision (e.g., state or province)

admin2Code - second-level administrative subdivision (e.g., county)

admin3Code - third-level administrative subdivision

admin4Code - fourth-level administrative subdivision

population - number of inhabitants

elevation - elevation in meters

digitalElevationModel - another way to measure elevation

timezone - timezone for this location

modificationDate - date of last modification for the GeoNames record

gazetteerRecord - the gazetteer record

Method Detail

getPrimaryCountryName

public String getPrimaryCountryName()

parseFromGeoNamesRecord

public static GeoName parseFromGeoNamesRecord(String inputLine)

Builds a GeoName object based on a single gazetteer record in the GeoNames geographical database.

Parameters:

inputLine - single line of tab-delimited text representing one record from the GeoNames gazetteer

Returns:

new GeoName object

parseFromGeoNamesRecord

public static GeoName parseFromGeoNamesRecord(String inputLine,
                              String preferredName)

Builds a GeoName object based on a single gazetteer record in the GeoNames geographical database.

Parameters:

inputLine - single line of tab-delimited text representing one record from the GeoNames gazetteer

preferredName - the preferred name of this GeoName as indicated by the GeoNames alternate names table

Returns:

new GeoName object

toString

public String toString()

For pretty-printing.

Overrides:

toString in class Object

getParentAncestryKey

public String getParentAncestryKey()

Get the ancestry key that can be used to identify the direct administrative parent of this GeoName. See getAncestryKey() for a description of an ancestry key. For example, the GeoName "Reston, VA" is found in the hierarchy:

• Reston
• • Fairfax County (admin2: "059")
  • • Virginia (admin1: "VA")
    • • United States (country code: "US")

Its parent ancestor key is "US.VA.059", which is the key returned by getAncestryKey() for the GeoName "Fairfax County."

Returns:

the ancestry key of the direct administrative parent of this GeoName; will be null for top-level elements such as countries

getAncestryKey

public String getAncestryKey()

Get the ancestry key that can be used to identify this administrative division. This method returns null for all feature types except the following FeatureClass.A records:

• Country (FeatureCode.PCL)
• First Administrative Division (FeatureCode.ADM1)
• Second Administrative Division (FeatureCode.ADM2)
• Third Administrative Division (FeatureCode.ADM3)
• Fourth Administrative Division (FeatureCode.ADM4)

The ancestry key includes the country and administrative division codes for all GeoNames in the ancestry path up to and including this GeoName. For example, the GeoName "Fairfax County" is found in the hierarchy:

• Fairfax County (admin2: "059")
• • Virginia (admin1: "VA")
  • • United States (country code: "US")

Its ancestry key is "US.VA.059". If no code is configured for the level of this administrative division, it will not be considered to have an ancestry key and will not be able to be referenced as the parent of other locations. (e.g. If this is an ADM4 and there is no admin4Code, getAncestryKey() will return null)

Returns:

the ancestry key for this administrative division or null if this GeoName is not an administrative division or its ancestry key cannot be derived.

isTopLevelAdminDivision

public boolean isTopLevelAdminDivision()

Is this GeoName a top-level administrative division (e.g. country, territory or similar)?

Returns:

true if this is a top-level administrative division

isTopLevelTerritory

public boolean isTopLevelTerritory()

Is this GeoName a top-level territory? A GeoName is considered to be a top-level territory if it is an A:TERR record and the name assigned to its primary country code is either the name of the GeoName or one of its configured alternate names.

Returns:

true if the GeoName is a top level territory

isDescendantOf

public boolean isDescendantOf(GeoName geoname)

Is this GeoName a descendant of the provided GeoName?

Parameters:

geoname - the GeoName to test

Returns:

true if the provided GeoName is hierarchically an ancestor of this GeoName

isAncestorOf

public boolean isAncestorOf(GeoName geoname)

Is this GeoName an ancestor of the provided GeoName?

Parameters:

geoname - the GeoName to test

Returns:

true if this GeoName is hierarchically an ancestor of the provided GeoName

getParent

public GeoName getParent()

Get the parent of this GeoName.

Returns:

the configured parent of this GeoName

setParent

public boolean setParent(GeoName prnt)

Set the parent of this GeoName.

Parameters:

prnt - the parent; if provided, parent.getAncestryKey() must match this.getParentAncestryKey(); null is ignored

Returns:

true if the parent was set, false if the parent was not the valid parent for this GeoName

isAncestryResolved

public boolean isAncestryResolved()

Check to see if the ancestry hierarchy has been completely resolved for this GeoName.

Returns:

true if all administrative parents have been resolved

getGeonameID

public int getGeonameID()

Get the ID of the record in geonames database.

Returns:

the ID

getName

public String getName()

Get the name of the geographical point (UTF-8).

Returns:

the name

getAsciiName

public String getAsciiName()

Get the name of the geographical point in plain ascii characters.

Returns:

the plain ascii name

getAlternateNames

public List<String> getAlternateNames()

Get the alternate names for the location.

Returns:

the alternate names; an empty List if none

getPreferredName

public String getPreferredName()

Gets the preferred name of this GeoName, if configured, otherwise returns the name.

Returns:

the preferred name

getLatitude

public double getLatitude()

Get the latitude in decimal degrees.

Returns:

the latitude

getLongitude

public double getLongitude()

Get the longitude in decimal degrees.

Returns:

the longitude

getFeatureClass

public FeatureClass getFeatureClass()

Get the major feature category. See http://www.geonames.org/export/codes.html

Returns:

the major feature category

getFeatureCode

public FeatureCode getFeatureCode()

Get the feature code. See http://www.geonames.org/export/codes.html

Returns:

the feature code

getPrimaryCountryCode

public CountryCode getPrimaryCountryCode()

Get the primary ISO-3166 2-letter country code.

Returns:

the primary country code

getAlternateCountryCodes

public List<CountryCode> getAlternateCountryCodes()

Get the alternate ISO-3166 2-letter country codes.

Returns:

the alternate country codes; empty List if none

getAdmin1Code

public String getAdmin1Code()

Get the code for the first level administrative division (e.g. a state in the US). This is mostly FIPS codes. ISO codes are used for US, CH, BE and ME. UK and Greece are using an additional level between country and FIPS code.

Returns:

the code for the first administrative division

getAdmin2Code

public String getAdmin2Code()

Get the code for the second level administrative division (e.g. a county in the US).

Returns:

the code for the second administrative division

getAdmin3Code

public String getAdmin3Code()

Get the code for the third level administrative division.

Returns:

the code for the third administrative division

getAdmin4Code

public String getAdmin4Code()

Get the code for the fourth level administrative division.

Returns:

the code for the fourth administrative division

getPopulation

public long getPopulation()

Get the total number of inhabitants.

Returns:

the population

getElevation

public int getElevation()

Get the elevation in meters.

Returns:

the elevation

getDigitalElevationModel

public int getDigitalElevationModel()

Get the digital elevation model, srtm3 or gtopo30, average elevation of 3''x3'' (ca 90mx90m) or 30''x30'' (ca 900mx900m) area in meters, integer. srtm processed by cgiar/ciat.

Returns:

the average elevation in meters

getTimezone

public TimeZone getTimezone()

Get the time zone for the geographical point.

Returns:

the time zone; may be null

getModificationDate

public Date getModificationDate()

Get the last modification date in the GeoNames database.

Returns:

the last modification date; may be null

getGazetteerRecord

public String getGazetteerRecord()

Get the gazetteer record for this GeoName.

Returns:

the gazetteer record this GeoName was parsed from

getGazetteerRecordWithAncestry

public String getGazetteerRecordWithAncestry()

Get the gazetteer records for this GeoName and its ancestors, separated by newline characters.

Returns:

the newline-separated gazetteer records for this GeoName and its ancestors.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object