<![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 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 ###
Zlib (1.2.5 and above) library only is needed
### Dynamic library ###
After extracting and compiling the API, a single library
file is created in the build/lib subfolder for both the Device Detection
and Carrier Identifcation APIs
### 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.
### Choosing an IP address ###
If the API is passed either a Map 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
- Remote-Addr
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:
```cpp
using namespace Mobi::Mtld::Da;
...
const char * ip = "62.40.34.220";
Carrier::CarrierApi carrierApi;
carrierApi.loadDataFromFile("/path/to/sample.dat"); // multiple calls will reload the data file each time
HeaderMap map;
map["Client-Ip"] = ip;
Carrier::HttpHeaders headers(map);
DeliveryContext dc(capi, headers);
// .... use the properties ....
if (!dc.empty()) {
std::cout << (string)dc["networkOperator"] << std::endl;
}
// get a single property
const Value *v;
v = dc["mcc"];
if (v) {
std::cout << "MCC: " << (string)*mccProp << std::endl;
}
```
### 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
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ (c) 2021 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 class="divider"></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 class="disabled"><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="README.Windows.html">C++ API and Windows</a></li><li><a href="README.ClientSide.html">Client-side Component</a></li><li class="divider"></li><li><a href="ApiDocs/index.html">DeviceAtlas ApiDocs</a></li></ul></div>]]>