# 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 = ""; 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 2023. 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 API Usage C</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li class="disabled"><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li><a href="README.Cpp.html">Device API C++</a></li><li><a href="README.Nginx.html">NGINX Module</a></li><li><a href="README.Apache2.html">Apache2 Module</a></li><li><a href="README.JsonConverter.html">Device Identification API C JSONConverter</a></li><li><a href="README.Go-DeviceApi.html">Device API Usage Go</a></li><li><a href="README.Go-Upgrade.html">Device API Upgrade Go</a></li><li><a href="https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html" target="_blank">Client-side component</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">C ApiDocs</a></li><li><a href="./ApiCppDocs/index.html">C ++ interface ApiDocs</a></li><li><a href="./Go-ApiDocs/carrier.html">Go ApiDocs Carrier</a></li><li><a href="./Go-ApiDocs/device.html">Go ApiDocs Device</a></li></ul></div>