<![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.
### Gem Files ###
The Carrier Identification API is comprised of one Gem file:
**mobi_mtld_da_carrier_api.gem** - The main API that loads the data file and
returns Mobile Carrier properties.
There is also an API wrapper that let you use the main API as a filter from a
Rails controller to transparently use the user's IP address and returns Mobile
Carrier properties: **mobi_mtld_da_carrier_api_web.gem**
### Dependencies ###
Third party libs and gems:
* On Ruby 1.8.x, the API depends on the iconv gem.
Gems provided:
* 'mobi_mtld_da_carrier_api' depends on 'mobi_mtld_da'.
* 'mobi_mtld_da_carrier_api_web' depends on 'mobi_mtld_da_carrier_api'.
### Usage ###
The API can be queried by passing any of the following to either the
property() or the properties() methods.
1. An **IPv4** 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.
### Choosing an IP address ###
If the API is passed a Hash 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
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:
```ruby
ip = "62.40.34.220"
carrier_api = Mobi::Mtld::Da::Carrier::CarrierApi.new
carrier_api.load_data_from_file "/path/to/sample.dat" # multiple calls will reload the data file each time
# get all properties
props = carrier_api.get_properties ip
# .... use the properties ....
if props.has_key?"networkOperator"
property = props.get "networkOperator"
operator_name = property.to_s
puts "networkOperator: " + operator_name
end
# get a single property
mcc_prop = carrier_api.get_property ip, "mcc"
if !mcc_prop.nil?
mcc = mcc_prop.to_s
puts "MCC: " + mcc
end
```
### Included Examples ###
Please see the examples directory for example code:
1. **basic_usage** - simple examples using the API
2. **singleton_wrapper** - shows how the API can be wrapped in a Singleton
3. **example_web_app** - 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
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ (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="disabled"><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="CarrierApiDocs/Mobi/Mtld/Da/Carrier/CarrierApi.html">Carrier API docs</a></li><li class="divider"></li><li class="divider"></li></ul></div>]]>