<![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 ###
No third party libraries are needed.
### Dynamic library ###
After extracting and compiling the API, a single library
file is created in the build/lib sub-folder for both the Device Detection
and Carrier Identification APIs
### Usage ###
The API can be queried by passing any of the following to the
`ci_searchrequest_add_http_header` function as a HTTP header name and
value pair to the `ci_atlas_lookup` function if a socket structure is intended to be used.
### Choosing an IP address ###
If the API is passed 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
...
const char * ip = "62.40.34.220";
ci_atlas_t carrier;
FILE *datfile = fopen("/path/to/sample.dat", "rb");
ci_errcode_t rc = ci_atlas_init(&carrier, datfile);
fclose(datfile);
if (rc == CI_OK) {
ci_searchrequest_t request;
ci_searchresult_t result;
size_t propcount;
ci_property_id prop;
ci_get_property_count(&carrier, &propcount);
ci_searchrequest_init(&request);
ci_searchrequest_add_http_header(request, "Client-Ip", ip);
rc = ci_atlas_search(&carrier, &request, &result);
...
// .... use the properties ....
for (size_t i = 0; i < propcount; i ++) {
size_t propcount;
enum ci_type proptype;
const char *propname = ci_get_property_name(&carrier, i);
rc = ci_get_property_value_count(&result, i, &propcount);
assert(rc == CI_OK);
rc = ci_get_property_value_type(&result, i, &proptype);
assert(rc == CI_OK);
for (size_t j = 0; j < propcount; j ++) {
switch (proptype) {
case CI_PROPTYPE_STRING: {
const char *val;
ci_get_property_value_string(&result, i, j, &val);
printf("%s => %s\n", propname, val);
break;
}
case CI_PROPTYPE_INT: {
intmax_t val;
ci_get_property_value_int(&result, i, j, &val);
printf("%s => %ld\n", propname, val);
break;
}
case CI_PROPTYPE_BOOL: {
bool val;
ci_get_property_value_bool(&result, i, j, &val);
printf("%s => %d\n", propname, (int)val);
break;
}
...
}
}
}
// get a single property
ci_get_property_id(&carrier, "mcc", &prop);
ci_format_property_value(result, prop, mccval, sizeof(mccval));
printf("MCC => %s\n", propname, mccval);
...
ci_searchrequest_fini(&request);
}
ci_atlas_fini(&carrier);
```
### 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 license 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 class="divider"></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 class="disabled"><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="README.Unix.html">C API and Unix</a></li><li><a href="README.Windows.html">C API and Windows</a></li><li class="divider"></li><li><a href="README.Nginx.html">C API and NGINX Module Installation</a></li><li class="divider"></li><li><a href="README.JsonConverter.html">C API JSONConverter</a></li><li><a href="https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html" target="_blank">Client-side Component</a></li><li><a href="README.ConnectivityAnalyser-Nginx.html">NGINX DeviceAtlas Connectivity Analyser</a></li><li><a href="README.ConnectivityAnalyser-Apache.html">Apache DeviceAtlas Connectivity Analyser</a></li><li><a href="ApiDocs/index.html">DeviceAtlas ApiDocs</a></li></ul></div>]]>