<![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 ###
This library does not depend on any third party libraries.
### DLL File ###
The Carrier Detection API is comprised of two classes included inside the
"DeviceAtlasCarrierApi.dll":
1. **CarrierApi** - The main API that loads the data file and returns Mobile
Carrier properties.
2. **CarrierApiWeb** - A small extension to the main API. For automatic
extraction of the client's IP address. Using this extention the current context
HttpRequest object can be used (HttpContext.Current.Request) or an HttpRequest
object can manually be passed to the API as the header resource.
### 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 **Dictionary<string, string>** of HTTP Header names to HTTP Header values.
The API will choose the most appropriate IP address to use.
3. An **HttpRequest** object. The API will choose the most appropriate IP
address to use.
4. Without arguments. The API will choose the most appropriate IP address to use
from the "HttpContext.Current.Request" object.
### Choosing An IP Address ###
If the API is passed either an array of HTTP Headers or nothing is passed 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:
```csharp
string ip = "62.40.34.220";
CarrierApi carrierApi = Carrier_CarrierApi();
// multiple calls will reload the data file each time
carrierApi.LoadDataFromFile("/path/to/carrier-data-file.dat");
// get all properties
Properties props = carrierApi.GetProperties(ip);
// .... use the properties ....
if (props.ContainsKey("networkOperator"))
{
Property property = props.Get("networkOperator");
string operatorName = property.AsString();
Console.WriteLine("networkOperator: " + operatorName);
}
// get a single property
Property mccProp = carrierApi.GetProperty(ip, "mcc");
if (mccProp != null)
{
string mcc = mccProp.AsString();
Console.WriteLine("MCC: " + mcc);
}
```
### Included Examples ###
Please see the Examples directory for example code:
1. **BasicUsage** - Simple examples using the API
2. **SingletonWrapper** - Shows how the API can be wrapped in a Singleton
3. **ExampleWebApp** - Simple page showing usage of the CarrerApiWeb class.
Note: By default examples 1 and 2 expects to find a carrier data file as
"[EXAMPLES_DIR]\data\carrier-data-file.dat" and example 3 expects to find a
carrier data file as "[EXAMPLES_DIR]\ExampleWebApp\data\carrier-data-file.dat".
Before trying the examples please place a carrier data file inside those
directories or change the path to a carrier file inside the example sources.
### 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) 2021 by 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><a href="README.DeviceApi.html">Device Detection API</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="DeviceApiDocs/html/classes.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="CarrierApiDocs/html/classes.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>]]>