# DeviceAtlas Carrier Identification API # The DeviceAtlas Carrier Identification API provides a way to lookup Mobile Carrier properties based on an IPv4 IP address. Using the IP address for a Mobile Carrier the API will return properties such as _networkOperator_, _networkBrand_, _countryCode_, _mcc_ and _mnc_. ### Data File ### The Carrier API relies on a data file to function. DeviceAtlas provides weekly carrier data file updates. Please ensure you are using an up-to-date data file. The data file can be downloaded from your account page or automated via the https://deviceatlas.com/getCarrierData page. ### Dependencies ### This library does not depend on any third party libraries. ### Library ### The DeviceAtlas Carrier Detection API consists of three libraries and each library has a separate jar file. #### DeviceAtlas common (deviceatlas-common-x.x.jar) #### Contains the shared libraries which are common between the DeviceAtlas APIs. When using the CarrierApi and CarrierApiWeb, this jar file must be included in the classpath. #### CarrierApi (deviceatlas-carrierapi-x.x.jar) #### The main CarrierApi that loads the Carrier data and detects and returns the properties for a set of request headers or an IP address. #### DeviceApiWeb (deviceatlas-carrierapiweb-x.x.jar) #### A small extension to the main API that allows passing of an HttpServletRequest object for automatic extraction of the request headers. Unless the HttpServletRequest object is not available or when processing an off-line set of header it is strongly recommended to use this library over the CarrierApi. All three jar files are required for this library to work. ### Usage ### The API can be queried by passing any of the following to either the getProperty() or the getProperties() methods. 1. An **IPv4** IP address string. _e.g. "62.40.34.220"_ 2. A **Map** of HTTP Header names to HTTP Header values. The API will choose the most appropriate IP address to use. 3. A **HttpServletRequest** object. The API will choose the most appropriate IP address to use. ### Choosing an IP address ### If the API is passed either a Map of HTTP Headers or a HttpServletRequest object it will try and choose the most suitable IP address for the end client. This is done by iterating over the following HTTP Headers. The first non-private, valid IP address is returned as the client IP. - X-Forwarded-For - Client-Ip - X-Client-Ip - rlnClientIpAddr - Proxy-Client-Ip - Wl-Proxy-Client-Ip - X-Forwarded - Forwarded-For - Forwarded The _X-Forwarded-For_ HTTP header can contain the client IP and multiple proxy IPs, the API parses the header to extract the client IP. ### Example ### The API has a very simple interface and can be used as follows: ```java String ip = "62.40.34.220"; CarrierApi carrierApi = new CarrierApi(); carrierApi.loadDataFromFile("/path/to/sample.dat"); // multiple calls will reload the data file each time // 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); } ``` ### Included Examples ### Please see the Examples directory for example code: 1. **BasicUsage** - simple examples using the API 2. **SingletonWrapper** - shows how the API can be wrapped in a Singleton 3. **ExampleWebApp** - Simple JSP page showing usage of the CarrierApiWeb module. This stores the loaded API in the ServletContext to avoid reloading the data file on every request. ### Master Carrier List ### For a listing of all Carrier names and associated data please see: https://deviceatlas.com/master-carrier-list The Carrier List is also available in CSV and XML formats. It can be downloaded from the above page or from the following download page using your Carrier Identification licence key: https://deviceatlas.com/getMasterCarrierList - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) 2021 by DeviceAtlas Limited. All rights reserved. https://deviceatlas.com _ <!-- HTML+JS for document formatting when opened in browser --> <div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li><a href="README.DeviceApi.html">Device Detection API</a></li><li><a href="README.DeviceApi-Config.html">Device Detection API Config</a></li><li><a href="README.Upgrade.html">Device Detection API Upgrade</a></li><li><a href="DeviceApiJavadoc/index.html">Device API Javadoc</a></li><li class="divider"></li><li class="disabled"><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="CarrierApiJavadoc/index.html">Carrier API Javadoc</a></li><li class="divider"></li><li><a href="README.ClientSide.html">Client-side Component</a></li><li><a href="README.ConnectivityAnalyser.html">Connectivity Analyser</a></li></ul></div>