Package com.iizix.geo

Class RegionLocation

  • All Implemented Interfaces:
    ILongitudeLatitude
    public class RegionLocation
extends java.lang.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 Detail

      • RegionLocation

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

      • RegionLocation

        public RegionLocation​(java.lang.String ipAddress,
                      java.lang.String continent,
                      java.lang.String continentCode,
                      java.lang.String country,
                      java.lang.String countryISO,
                      int countryConfidence,
                      java.lang.String region,
                      java.lang.String regionCode,
                      java.lang.String city,
                      java.lang.String cityISO,
                      int cityConfidence,
                      java.lang.String zipCode,
                      int zipCodeConfidence,
                      double longitude,
                      double latitude,
                      double accuracyRadius,
                      java.lang.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 Detail

      • 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 java.lang.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 java.lang.String getError()
        Gets the service provider error message why this request failed.
        Returns:
        The error message, or null for no error.

      • getContinent

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

      • getContinentCode

        public java.lang.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 java.lang.String getCountry()
        Gets the country name, e.g. 'United States'.
        Returns:
        The country name.

      • getCountryISO

        public java.lang.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 java.lang.String getRegion()
        Gets the region name, e.g. 'California', null for none.
        Returns:
        The region name.

      • getRegionCode

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

      • getCity

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

      • getCityISO

        public java.lang.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 java.lang.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 java.lang.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 java.lang.Object
        Returns:
        The hashCode.

      • equals

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

      • toString

        public java.lang.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 java.lang.Object
        Returns:
        The string.

      • timezoneFrom

        public static RegionLocation.Timezone timezoneFrom​(java.lang.String id,
                                                   java.lang.String code,
                                                   java.lang.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​(java.lang.String code,
                                                   java.lang.String name,
                                                   java.lang.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:
        java.lang.NullPointerException - If code is null.

      • currencyFrom

        public static RegionLocation.Currency currencyFrom​(java.lang.String code,
                                                   java.lang.String name,
                                                   java.lang.String pluralName,
                                                   java.lang.String symbol,
                                                   java.lang.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​(java.lang.String asn,
                                                       java.lang.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​(java.lang.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.