<![CDATA[
# DeviceAtlas Carrier Identification API #
The DeviceAtlas Carrier Identification API provides a way to lookup Mobile
Carrier properties based on an IPv4/IPv6 address. Using the IP address for a
Mobile Carrier the API will return properties such as _networkOperator_,
_networkBrand_, _networkType_, _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.
### Library ###
The DeviceAtlas Enterprise API comprises one Gem file which includes both the
Device and Carrier Identification APIs.
The Carrier Identification API namespace and main class is:
**DeviceAtlas::Carrier::CarrierApi**
There is also an API wrapper that lets you use the main API as a filter from a
Rails controller to transparently use the user's IP address: **DeviceAtlas::Carrier::CarrierApiWeb**
### Dependencies ###
This library does not depend on any third party libraries.
### Input ###
The API can be queried by passing any of the following to either the
get_property() or the get_properties() methods.
1. An **IPv4** or **IPv6** IP address string. _e.g. "62.40.34.220"_
2. A **Hash** of HTTP Header names to HTTP Header values. The API will choose the
most appropriate IP address to use.
3. An **[Net::HTTP]** request object.
### Choosing an IP address ###
If the API is passed a Hash of HTTP headers it will try to choose the most suitable
IP address for the end client. This is done by iterating over the below 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.
### Basic Usage ###
The API has a very simple interface and can be used as follows:
_Initialize API_
```ruby
require 'deviceatlas'
carrier_api = DeviceAtlas::Carrier::CarrierApi.new
carrier_api.load_data_from_file "/path/to/carrier-data-file.dat"
```
_Get the properties_
```ruby
properties = carrier_api.get_properties "62.40.34.220"
```
_Use the properties_
```ruby
if !properties.nil?
puts("Network Operator: #{properties['networkOperator']}")
end
```
### Included Examples ###
Please see the **Examples/carrier/** directory for more examples:
1. **basic_usage_cli_detect** - simple examples using the API
2. **basic_usage_cli_detect_list_of_ips** - shows how the API can be used for batch processing
3. **basic_usage_web** - controller and viewer files for Rails projects
### 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/DeviceAtlas/Device/DeviceApi.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/DeviceAtlas/Carrier/CarrierApi.html">Carrier API Docs</a></li><li class="divider"></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.html">Connectivity Analyser</a></li></ul></div>]]>