# 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. The Carrier API has the capability to automatically download and load the latest data file on a scheduled basis. Please note that basic telemetry data such as the number of API lookups are collected when using the download and load functionality. If however your integration cannot make use of the automatic download and load feature it is recommended to download the data file on a regular basis. The data file can be downloaded from your account page or automated via the https://deviceatlas.com/getCarrierData page. Please see the [Data File Configuration documentation](README.DataFileConfig.html) and the [Carrier Data guide](https://deviceatlas.com/resources/getting-the-data/carrier-data) for more information. #### Loading the data file #### The Carrier API provides multiple methods to load the data file. ##### Downloading and loading the data file ##### The following examples download the data file, save it to the file system, load it into the Carrier API and schedule a background task to download and load a fresh data file at a configured time in the future. Please see the [Data File Configuration documentation](README.DataFileConfig.html) to obtain the data file download URL and for data file configuration options. ```csharp using Com.DeviceAtlas.Carrier; CarrierApi carrierApi = new CarrierApi(); string dataFileUrl = <data file download URL>; // Load using custom configuration DataFileConfig dataFileConfig = DataFileConfigBuilder.Create(<data file download URL>).FileDirectory(<persistent download directory>).BuildCarrier(); carrierApi.DownloadAndLoadDataFile(dataFileConfig); // Load using default configuration carrierApi.DownloadAndLoadDataFile(dataFileUrl); ``` ##### Loading an existing data file ##### The following examples show how to load a data file that is already on the filesystem. ```csharp using Com.DeviceAtlas.Carrier; CarrierApi carrierApi = new CarrierApi(); // Load data from file path carrierApi.LoadDataFromFile(<data file path>); ``` ### 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 **Dictionary<string, string>** of HTTP Header names to HTTP Header values. The API will choose the most appropriate IP address to use. 3. An **HttpRequest** object. The API will choose the most appropriate IP address to use. 4. **(.NET Framework Only)** Without arguments. The API will choose the most appropriate IP address to use from the "HttpContext.Current.Request" object. ### Choosing An IP Address ### If the API is passed either an array of HTTP Headers or nothing is passed 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: ```csharp string ip = "62.40.34.220"; CarrierApi carrierApi = CarrierApi(); carrierApi.DownloadAndLoadDataFile(<data file download URL>); // 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 = props.Get("networkOperator"); string operatorName = property.AsString(); Console.WriteLine("networkOperator: " + operatorName); } // get a single property Property mccProp = carrierApi.GetProperty(ip, "mcc"); if (mccProp != null) { string mcc = mccProp.AsString(); Console.WriteLine("MCC: " + mcc); } ``` ### Included Examples ### Please see the Examples directory for example code: 1. **BasicUsage:** Located at Examples/Carrier/basic-usage 2. **SingletonWrapper:** Located at Examples/Carrier/web-usage ### 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) DeviceAtlas Limited 2024. All Rights Reserved. _ <!-- 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.Installation.html">Enterprise API Installation</a></li><li><a href="README.DataFileConfig.html">Data File Configuration</a></li><li><a href="README.DeviceApi.html">Device Identification API</a></li><li class="disabled"><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li class="divider"></li><li><a href="./DeviceApiDocs/classes.html">Device API Docs</a></li><li><a href="./CarrierApiDocs/classes.html">Carrier API Docs</a></li></ul></div>