< and
the [Carrier Data guide](https://deviceatlas.com/resources/getting-the-data/carrier-data)
for more information.
#### Loading the data file ####
The Carrier API provides multiple methods to load the data file.
##### Downloading and loading the data file #####
The following examples download the data file, save it to the file system,
load it into the Carrier API and schedule an auto-download and reload to ensure
the API has the latest version of data file.
Please see the [Data File Configuration documentation](README.DataFile.html)
to obtain the data file download URL and for data file configuration options.
_Example: using default configuration_
```php
use DeviceAtlas\Carrier\CarrierApi;
$carrierApi = CarrierApi();
$carrierApi->downloadAndLoadDataFile(<data file download URL>);
```
_Example: using custom configuration_
```php
use DeviceAtlas\Carrier\CarrierApi;
use DeviceAtlas\DataFile;
$dataFileUrl = <data file download URL>;
$downloadDir = <persistent download directory>;
$carrierApi = CarrierApi();
$dataFile = DataFile::Builder($dataFileUrl)->fileDirectory($downloadDir)->buildCarrierDataFile();
$carrierApi->downloadAndLoadDataFileFromUrl($dataFile);
```
##### Loading an existing data file #####
The following example shows how to load a data file that is already on the filesystem.
```php
use DeviceAtlas\Carrier\CarrierApi;
$carrierApi = CarrierApi();
$carrierApi->loadDataFromFile(<data file path>);
```
### 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. An **Array** of HTTP Header names to HTTP Header values. The API will choose
the most appropriate IP address to use when using `CarrierApiWeb` extension.
3. Without arguments. The API will choose the most appropriate IP address to use
from the $_SERVER when using `CarrierApiWeb` extension.
### 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:
```php
use DeviceAtlas\Carrier\CarrierApi;
$IPv4 = "62.40.34.220";
$carrierApi = CarrierApi();
$carrierApi->loadDataFromFile(<data file path>);
// Get all the properties
$props = $carrierApi->getProperties($IPv4);
// Use the properties
if ($props->containsKey('networkOperator')) {
$operatorName = $props->get('networkOperator');
echo 'networkOperator: ' . $operatorName->asString() . "\n";
}
// Get a single property
$mccProp = $carrierApi->getProperty($IPv4, 'mcc');
if ($mccProp !== null) {
echo 'MCC: ' . $mccProp->asString() . "\n";
}
```
### Examples ###
Please see the `Examples/` directory for examples that encompass the following scenarios:
1. **Basic usage** - Simple example using the API
2. **Example web app** - Simple page showing usage of the `CarrierApiWeb` class.
### 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 2024. 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.DataFile.html">Data File Configuration</a></li><li><a href="README.DeviceApi.html">Device API Usage</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.DataFileOptimizer.html">Data File Optimizer</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li class="disabled"><a href="README.CarrierApi.html">Carrier Identification API</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">DeviceAtlas API Docs</a></li></ul></div>]]>