Package com.iizix.geo

Class RegionLocation

java.lang.Object
com.iizix.geo.RegionLocation
All Implemented Interfaces:
ILongitudeLatitude
public class RegionLocation extends Object implements ILongitudeLatitude
Region location information, originating from a host name or IPv4/IPv6 address.

Programming note: DO NOT COMPARE WITH Double.NaN as e.g. value==Double.NaN, use Double.isNaN(double) instead as comparison is always false.

Author:
Christopher Mindus

  • Constructor Details

    • RegionLocation

      public RegionLocation(String ipAddress, String error)
      Creates an instance of the region information.
      Parameters:
      ipAddress - The IP address.
      error - The error string.

    • RegionLocation

      public RegionLocation(String ipAddress, String continent, String continentCode, String country, String countryISO, int countryConfidence, String region, String regionCode, String city, String cityISO, int cityConfidence, String zipCode, int zipCodeConfidence, double longitude, double latitude, double accuracyRadius, String geoNameID, RegionLocation.Timezone timezone, RegionLocation.Currency currency, RegionLocation.Language[] languages, RegionLocation.Connection connection, RegionLocation.Security security)
      Creates an instance of the region information.
      Parameters:
      ipAddress - The IP address.
      continent - Continent name, e.g. 'North America'.
      continentCode - Continent code, e.g. 'NA'.
      country - Country name, e.g. 'United States'.
      countryISO - ISO code for the country, e.g. 'US'.
      countryConfidence - Confidence (0-100) of the country, -1 for none, e.g. '99'.
      region - Region name, e.g. 'California'.
      regionCode - Region code, e.g. 'CA'.
      city - City name, null for none, e.g. 'Minneapolis'.
      cityISO - City ISO code, null for none, e.g. 'MN'.
      cityConfidence - Confidence (0-100) of the city, -1 for none, e.g. '50'.
      zipCode - Zip code, null for none, e.g. '55455'.
      zipCodeConfidence - Confidence (0-100) of the zip code, -1 for none, e.g. '40'.
      longitude - Longitude, e.g. '44.9733'.
      latitude - Latitude, e.g. '-93.2323'.
      accuracyRadius - Accuracy radius of the longitude/latitude location, -1d for none, e.g. '3'.
      geoNameID - The unique geoname identifier in accordance with the Geonames Registry, null for none.
      timezone - Time zone, null for none.
      currency - The currency, null for none.
      languages - Array of languages spoken in the country, null for none.
      connection - The connection, null for none.
      security - The security, null for none.

  • Method Details

    • getCreationTime

      public long getCreationTime()
      Gets the creation time of this instance.
      Returns:
      Time in milliseconds since the epoch.

    • getRequestDuration

      public long getRequestDuration()
      Gets the time it took to retrieve this information in the first place. If cached, this information is not relevant.
      Returns:
      The request duration in milliseconds.

    • getIPAddress

      public String getIPAddress()
      Gets the IP address.
      Returns:
      The IP address string.

    • isValid

      public boolean isValid()
      Checks if the information is valid, i.e. that there is no error present.
      Returns:
      true if valid, false if an error is present.

    • hasError

      public boolean hasError()
      Checks if the information is not valid, i.e. if there is an error present.
      Returns:
      true if there is an error, false if information is valid.

    • getError

      public String getError()
      Gets the service provider error message why this request failed.
      Returns:
      The error message, or null for no error.

    • getContinent

      public String getContinent()
      Gets the continent name, e.g. 'North America', null for none.
      Returns:
      The continent name.

    • getContinentCode

      public String getContinentCode()
      Gets the continent code, e.g. 'NA', null for none. The normal codes are:
      • AF - Africa,
      • AS - Asia,
      • EU - Europe,
      • NA - North America,
      • OC - Oceania,
      • SA - South America,
      • AN - Antarctica.
      Returns:
      The continent code.

    • getCountry

      public String getCountry()
      Gets the country name, e.g. 'United States'.
      Returns:
      The country name.

    • getCountryISO

      public String getCountryISO()
      Gets the ISO code for the country, e.g. 'US'.
      Returns:
      The country ISO code.

    • getCountryConfidence

      public int getCountryConfidence()
      Gets the confidence (0-100) of the country, -1 for none, e.g. '99'.
      Returns:
      The country confidence.

    • getRegion

      public String getRegion()
      Gets the region name, e.g. 'California', null for none.
      Returns:
      The region name.

    • getRegionCode

      public String getRegionCode()
      Gets the region code, e.g. 'CA', null for none.
      Returns:
      The region code.

    • getCity

      public String getCity()
      Gets the city name, null for none, e.g. 'Minneapolis'.
      Returns:
      The city name.

    • getCityISO

      public String getCityISO()
      Gets the city ISO code, null for none, e.g. 'MN'.
      Returns:
      The city ISO code.

    • getCityConfidence

      public int getCityConfidence()
      Gets the confidence (0-100) of the city, -1 for none, e.g. '50'.
      Returns:
      The city confidence.

    • getZipCode

      public String getZipCode()
      Gets the zip code, null for none, e.g. '55455'.
      Returns:
      The zip code.

    • getPostalCodeConfidence

      public int getPostalCodeConfidence()
      Gets the confidence (0-100) of the zip code, -1 for none, e.g. '40'.
      Returns:
      The zip code confidence.

    • getLongitude

      public double getLongitude()
      Gets the longitude, e.g. '44.9733'.
      Specified by:
      getLongitude in interface ILongitudeLatitude
      Returns:
      The longitude, Double.NaN for none.

    • getLatitude

      public double getLatitude()
      Gets the latitude, e.g. '-93.2323'.
      Specified by:
      getLatitude in interface ILongitudeLatitude
      Returns:
      The latitude, Double.NaN for none.

    • getAccuracyRadius

      public double getAccuracyRadius()
      Gets the accuracy radius of the longitude/latitude location, -1d for none, e.g. '3'.
      Returns:
      The accuracyRadius, -1d for none.

    • getGeoNameID

      public String getGeoNameID()
      Gets the unique geoname identifier in accordance with the Geonames Registry, null for none.
      Returns:
      The geoNameID, or null if not available.

    • getTimezone

      public RegionLocation.Timezone getTimezone()
      Gets the time zone, null for none.
      Returns:
      The Timezone instance, null if this information is not available.

    • getCurrency

      public RegionLocation.Currency getCurrency()
      The currency, null for none.
      Returns:
      The Currency instance or null for none.

    • getLanguages

      public RegionLocation.Language[] getLanguages()
      The languages spoken in the country, null if information is not available.
      Returns:
      The array of Language instances if this information is available, null otherwise.

    • getConnection

      public RegionLocation.Connection getConnection()
      The connection, null for none.
      Returns:
      The Connection instance, or null if this information is not available.

    • getSecurity

      public RegionLocation.Security getSecurity()
      The security, null for none.
      Returns:
      The Security instance, or null if this information is not available.

    • hashCode

      public int hashCode()
      Gets the hash code.
      Overrides:
      hashCode in class Object
      Returns:
      The hashCode.

    • equals

      public boolean equals(Object obj)
      Checks for equality.
      Overrides:
      equals in class Object
      Returns:
      true if objects are equal, false otherwise.

    • toString

      public String toString()
      Gets a string representation of this instance as "className[countryISO=..,country=..,...]". Values that are null or Double.isNaN(value) are not present.
      Overrides:
      toString in class Object
      Returns:
      The string.

    • timezoneFrom

      public static RegionLocation.Timezone timezoneFrom(String id, String code, Integer gmtOffset)
      Creates an instance of a Timezone or get a cached version.
      Parameters:
      id - The timezone ID, null for none.
      code - The timezone code, null for none.
      gmtOffset - The GMT offset of the given time zone in seconds, e.g. -25200 for PST's -7h GMT offset, null for none.
      Returns:
      The timezone instance, or null if id is null.

    • languageFrom

      public static RegionLocation.Language languageFrom(String code, String name, String nativeName)
      Creates or gets a cached version of the language.
      Parameters:
      code - The 2-letter language code for the given language.
      name - The name (in the API request's main language) of the given language, e.g. 'Portuguese', null for none.
      nativeName - The native name of the given language, e.g. 'Português', null for none.
      Throws:
      NullPointerException - If code is null.

    • currencyFrom

      public static RegionLocation.Currency currencyFrom(String code, String name, String pluralName, String symbol, String nativeSymbol)
      Creates or gets a cached version of the currency.
      Parameters:
      code - The 3-letter language code for the given currency code, never null.
      name - Name in English of the given currency, null for none.
      pluralName - Plural name of the given currency, null for none.
      symbol - Symbol letter of the given currency, null for none.
      nativeSymbol - Native symbol letter of the given currency, null for none.
      Returns:
      A Currency instance if code is not null, otherwise null.

    • connectionFrom

      public static RegionLocation.Connection connectionFrom(String asn, String isp)
      Creates a Connection instance from the ASN and ISP parameters.
      Parameters:
      asn - The Autonomous System Number associated with the IP, null if not defined.
      isp - The name of the ISP associated with the IP, null if not defined.
      Returns:
      A new Connection instance if either ASN or ASP is non-null.

    • securityThreadLevelFrom

      public static int securityThreadLevelFrom(String s)
      Parses the threat level string to a level of:
      • 0 = unknown,
      • 1 = low,
      • 2 = medium,
      • 3 = high.
      Parameters:
      s - The string, perhaps null.
      Returns:
      A security thread level 0-3.