Package com.deviceatlas.carrier

Class CarrierApi

java.lang.Object
com.deviceatlas.BaseDeviceAtlasApi
com.deviceatlas.carrier.CarrierApi
All Implemented Interfaces:
DeviceAtlasApi
Direct Known Subclasses:
CarrierApiWeb, CarrierApiWebJakarta
public class CarrierApi extends BaseDeviceAtlasApi

The main class for the Carrier Detection API. Used to load the data file and perform lookups using IPv4 and IPv6 addresses. If you want to use the DeviceAtlas Carrier API in a servlet container then it is strongly recommended to use CarrierApiWeb instead of this library.

Please note that it is advisable to load only a single instance of this class to avoid multiple loadings of the data file. This can be done in a Web Container by storing a reference to it in the ServletContext.

Example usage:

     String ip = "62.40.34.220";
     CarrierApi carrierApi = new CarrierApi();
     carrierApi.loadDataFromFile("/path/to/sample.dat");

     // get all properties
     Properties props = carrierApi.getProperties(ip);
     // .... use the properties ....
     if (props.containsKey("networkOperator"))  {
         Property property = (Property)props.get("networkOperator");
         String operatorName = property.asString();
         System.out.println("networkOperator: "+operatorName);
     }

     // get a single property
     Property mccProp = carrierApi.getProperty(ip, "mcc");
     if (mccProp != null) {
         String mcc = mccProp.asString();
         System.out.println("MCC: " + mcc);
     }

Please see the code in the Examples directory for additional samples.

  • Field Details

    • HEADERS_TO_CHECK

      public static final String[] HEADERS_TO_CHECK
      A list of HTTP headers to choose the original client IP address from. In addition to these the RemoteAddr (REMOTE_ADDR) is also used as a final fallback.

  • Constructor Details

    • CarrierApi

      public CarrierApi()

  • Method Details

    • loadDataFromFile

      public void loadDataFromFile(String path) throws DataLoadingException
      Load the data file from the provided path. The data file is reloaded every time this method is called.
      Parameters:
      path - The path on disk to the data file.
      Throws:
      DataLoadingException - thrown when there is a problem with the data file.

    • loadDataFromClassPath

      public void loadDataFromClassPath(String fileName) throws DataLoadingException
      Load the data file from the class path. The data file is reloaded every time this method is called.
      Parameters:
      fileName - The name of the file on the class path
      Throws:
      DataLoadingException - thrown when there is a problem with the data file.

    • loadDataFromStream

      public void loadDataFromStream(InputStream inputStream) throws DataLoadingException
      Load the data from an input stream.
      Parameters:
      inputStream - Input stream
      Throws:
      DataLoadingException - thrown when there is a problem with the data file.

    • getDataFileCopyright

      public String getDataFileCopyright()
      Returns the data file copyright text.
      Returns:
      the copyright

    • getDataFileCreationDate

      public String getDataFileCreationDate()
      Returns the data file creation date in ISO8601 format.
      Returns:
      the creationDate

    • getDataFileVersion

      public String getDataFileVersion()
      Returns the version of the data file.
      Returns:
      the version

    • getApiVersion

      public static String getApiVersion()
      Returns the version of the Carrier API.
      Returns:
      the Carrier API version

    • getProperties

      public Properties getProperties(String ip)
      Get the Carrier properties for a given IP address.
      Parameters:
      ip - The IP address to find carrier properties for.
      Returns:
      The found properties or null if no properties found.

    • getProperties

      public Properties getProperties(Map<String,String> keyVals)

      Get the Carrier properties for a given Map of HTTP Headers. The API will choose the most appropriate IP to use.

      The following headers are checked in order to find the most suitable IP address.

      • X-Forwarded-For
      • Client-Ip
      • X-Client-Ip
      • rlnClientIpAddr
      • Proxy-Client-Ip
      • Wl-Proxy-Client-Ip
      • X-Forwarded
      • Forwarded-For
      • Forwarded
      Parameters:
      keyVals - A map of HTTP header names to HTTP header values. Both must be Strings.
      Returns:
      The found properties or null if no properties found.

    • getProperty

      public Property getProperty(String ip, String propertyName) throws InvalidPropertyNameException

      Try to obtain a specific property for a given IP address.

      Note: if multiple properties are needed for the same IP it is more efficient to call getProperties() once rather than repeated calls to getProperty().

      Parameters:
      ip - The IP address to find carrier properties for.
      propertyName - The name of the property to return
      Returns:
      The Property or null if no property found.
      Throws:
      InvalidPropertyNameException - Thrown if the property name does not exist.

    • getProperty

      public Property getProperty(Map<String,String> keyVals, String propertyName) throws InvalidPropertyNameException

      Try to obtain a specific property for a given Map of HTTP Headers. The API will choose the most appropriate IP to use.

      Note: if multiple properties are needed for the same IP it is more efficient to call getProperties() once rather than repeated calls to getProperty().

      Parameters:
      keyVals - A map of HTTP header name to HTTP header value. Both must be Strings.
      propertyName - The name of the property to return
      Returns:
      The Property or null if no property found.
      Throws:
      InvalidPropertyNameException - Thrown if the property name does not exist.

    • getPropertyNames

      public Set<PropertyName> getPropertyNames()
      A Set of all the possible property names. The Set contains PropertyName objects that each have a String name and an associated data type.
      Returns:
      A Set of property names

    • getIp

      public String getIp(Map<String,String> keyVals)
      Get the most suitable IP address from the given keyVals set of HTTP headers. This function checks the headers defined in HEADERS_TO_CHECK.
      Parameters:
      keyVals - A map of HTTP header name to HTTP header value
      Returns:
      The most suitable IP or NULL if a suitable IP could not be found.

    • isPublicIp

      public static boolean isPublicIp(String ipStr)
      An IP address is considered public if it is not in any of the following ranges: 
        1) any local address
     IP:  0

  2) a local loopback address
     range:  127/8

  3) a site local address i.e. IP is in any of the ranges:
     range:  10/8
     range:  172.16/12
     range:  192.168/16

  4) a link local address
     range:  169.254/16
      Parameters:
      ipStr - The IP address to check
      Returns:
      True if it is a public IP, false if the IP is invalid or is not public.

    • getDeviceAtlasApiVersion

      public String getDeviceAtlasApiVersion()