<![CDATA[
# 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 in an automated way 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 two libraries as below:
#### DeviceAtlas Common (Api/mobi/mtld/da/*) ####
Contains the shared libraries which are common between the DeviceAtlas APIs.
When using the CarrierApi the required files from this library
will be included automatically by the API. Keep the relative paths of the
libraries as they are in the downloaded package.
#### CarrierApi (Api/mobi/mtld/da/carrier/carrier_api/CarrierApi) ####
The main class that loads the Carrier data and detects and returns the
properties for a set of request headers or an IP address.
### 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 dict 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 mobi.mtld.da.carrier.carrier_api import CarrierApi
ip = "62.40.34.220";
carrier_api = CarrierApi()
carrier_api.load_data_from_file("/path/to/sample.dat") // multiple calls will reload the data file each time
// get all properties
props = carrier_api.get_properties(ip);
// .... use the properties ....
if "networkOperator" in props:
property = props["networkOperator"]
operator_name = str(property)
print("networkOperator: %s" % operatorName)
// get a single property
mccProp = carrier_api.get_property(ip, "mcc")
if mccProp is not None:
mcc = str(mccProp)
print("MCC: %s" % mcc)
```
### Included Examples ###
Please see the Examples directory for example code:
1. **BasicUsage** - Simple examples using the API
2. **ExampleWebApp**
Simple Django application showing usage of the CarrierApi module.
Django 1.4+ is required.
Note: Please download the latest version of the carrier data file and change the path to
the downloaded carrier file in the example sources before runing the examples.
### 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 2021. 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-Web.html">Device Detection for Web</a></li><li><a href="README.DeviceApi-Apps.html">Device Detection for Apps</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="./ApiDocs/mobi.mtld.da.device.device_api.DeviceApi-class.html">Device API Docs</a></li><li class="divider"></li><li class="disabled"><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="./ApiDocs/mobi.mtld.da.carrier.carrier_api.CarrierApi-class.html">Carrier API Docs</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>]]>