GeoName (CLAVIN 2.1.0 API)

All Known Implementing Classes:

BasicGeoName, LazyAncestryGeoName
```
public interface GeoName
```
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` sentinel value used in place of null when numeric value in GeoNames record is not provided (see: geonameID, latitude, longitude, population, elevation, digitalElevationModel)

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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.
`Integer`	`getParentId()` Get the ID of the 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()` Get the name of the country associated with the primary country code.
`TimeZone`	`getTimezone()` Get the time zone for the geographical point.
`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.
`boolean`	`setParent(GeoName prnt)` Set the parent of this GeoName.

- Field Detail
  - OUT_OF_BOUNDS
```
static final int OUT_OF_BOUNDS
```
    sentinel value used in place of null when numeric value in GeoNames record is not provided (see: geonameID, latitude, longitude, population, elevation, digitalElevationModel)
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getPrimaryCountryName
```
String getPrimaryCountryName()
```
    Get the name of the country associated with the primary country code.
    
    Returns:
    
    the name of the primary country
  - getParentAncestryKey
```
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
```
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
```
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
```
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
```
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
```
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
  - getParentId
```
Integer getParentId()
```
    Get the ID of the parent of this GeoName.
    
    Returns:
    
    the ID of the parent of this GeoName
  - getParent
```
GeoName getParent()
```
    Get the parent of this GeoName.
    
    Returns:
    
    the configured parent of this GeoName
  - setParent
```
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
```
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
```
int getGeonameID()
```
    Get the ID of the record in geonames database.
    
    Returns:
    
    the ID
  - getName
```
String getName()
```
    Get the name of the geographical point (UTF-8).
    
    Returns:
    
    the name
  - getAsciiName
```
String getAsciiName()
```
    Get the name of the geographical point in plain ascii characters.
    
    Returns:
    
    the plain ascii name
  - getAlternateNames
```
List<String> getAlternateNames()
```
    Get the alternate names for the location.
    
    Returns:
    
    the alternate names; an empty List if none
  - getPreferredName
```
String getPreferredName()
```
    Gets the preferred name of this GeoName, if configured, otherwise returns the name.
    
    Returns:
    
    the preferred name
  - getLatitude
```
double getLatitude()
```
    Get the latitude in decimal degrees.
    
    Returns:
    
    the latitude
  - getLongitude
```
double getLongitude()
```
    Get the longitude in decimal degrees.
    
    Returns:
    
    the longitude
  - getFeatureClass
```
FeatureClass getFeatureClass()
```
    Get the major feature category. See http://www.geonames.org/export/codes.html
    
    Returns:
    
    the major feature category
  - getFeatureCode
```
FeatureCode getFeatureCode()
```
    Get the feature code. See http://www.geonames.org/export/codes.html
    
    Returns:
    
    the feature code
  - getPrimaryCountryCode
```
CountryCode getPrimaryCountryCode()
```
    Get the primary ISO-3166 2-letter country code.
    
    Returns:
    
    the primary country code
  - getAlternateCountryCodes
```
List<CountryCode> getAlternateCountryCodes()
```
    Get the alternate ISO-3166 2-letter country codes.
    
    Returns:
    
    the alternate country codes; empty List if none
  - getAdmin1Code
```
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
```
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
```
String getAdmin3Code()
```
    Get the code for the third level administrative division.
    
    Returns:
    
    the code for the third administrative division
  - getAdmin4Code
```
String getAdmin4Code()
```
    Get the code for the fourth level administrative division.
    
    Returns:
    
    the code for the fourth administrative division
  - getPopulation
```
long getPopulation()
```
    Get the total number of inhabitants.
    
    Returns:
    
    the population
  - getElevation
```
int getElevation()
```
    Get the elevation in meters.
    
    Returns:
    
    the elevation
  - getDigitalElevationModel
```
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
```
TimeZone getTimezone()
```
    Get the time zone for the geographical point.
    
    Returns:
    
    the time zone; may be null
  - getModificationDate
```
Date getModificationDate()
```
    Get the last modification date in the GeoNames database.
    
    Returns:
    
    the last modification date; may be null
  - getGazetteerRecord
```
String getGazetteerRecord()
```
    Get the gazetteer record for this GeoName.
    
    Returns:
    
    the gazetteer record this GeoName was parsed from
  - getGazetteerRecordWithAncestry
```
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.

Interface GeoName

Field Summary

Method Summary

Field Detail

OUT_OF_BOUNDS

Method Detail

getPrimaryCountryName

getParentAncestryKey

getAncestryKey

isTopLevelAdminDivision

isTopLevelTerritory

isDescendantOf

isAncestorOf

getParentId

getParent

setParent

isAncestryResolved

getGeonameID

getName

getAsciiName

getAlternateNames

getPreferredName

getLatitude

getLongitude

getFeatureClass

getFeatureCode

getPrimaryCountryCode

getAlternateCountryCodes

getAdmin1Code

getAdmin2Code

getAdmin3Code

getAdmin4Code

getPopulation

getElevation

getDigitalElevationModel

getTimezone

getModificationDate

getGazetteerRecord

getGazetteerRecordWithAncestry