# 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 daily 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 via https://deviceatlas.com/getCarrierData page. For more information please see: https://deviceatlas.com/resources/getting-the-data ### Usage ### The API can be queried by passing any of the following to either the get_property() or the get_properties() methods. 1. An **IPv4** IP address string. _e.g. "62.40.34.220"_ 2. A **Dictionary** of HTTP Header names to HTTP Header values. The API will choose the most appropriate IP address to use. ### Choosing an IP Address ### If the API is passed a dictionary of HTTP Headers 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: ```python from com.deviceatlas.carrier.carrier_api import CarrierApi ip = "62.40.34.220" carrier_api = CarrierApi() carrier_api.load_data_from_file("/path/to/data.dat") # multiple calls will reload the data file each time # get all properties properties = carrier_api.get_properties(ip) # .... use the properties .... if "networkOperator" in properties: property = properties["networkOperator"] operator_name = str(property) print("networkOperator: %s" % operator_name) # get a single property mcc_property = carrier_api.get_property(ip, "mcc") if mcc_property is not None: mcc = str(mcc_property) print("MCC: %s" % mcc) ``` ### Included Examples ### Please see the Examples directory for examples that encompass the following scenarios: 1. **Usage within a command line application** - Located at Examples/carrier/basic_usage_cli 2. **Analyse a list of IPs** - Located at Examples/carrier/basic_usage_cli_detect_list_of_ips 3. **Usage within a web application** - Located at Examples/carrier/basic_usage_web ### 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. _ 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 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="disabled"><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">DeviceAtlas API Docs</a></li></ul></div>