< 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 a background task to download and load
a fresh data file at a configured time in the future.
Please see the [Data File Configuration documentation](README.DataFile.html)
to obtain the data file download URL and for data file configuration options.
```java
CarrierApi carrierApi = new CarrierApi();
String dataFileUrl = <data file download URL>;
// Load using custom configuration
DataFile dataFile = new DataFile.Builder(dataFileUrl).fileDirectory(<persistent download directory>).buildCarrierDataFile();
carrierApi.downloadAndLoadDataFile(dataFile);
// Load using default configuration
carrierApi.downloadAndLoadDataFile(dataFileUrl);
```
##### Loading an existing data file #####
The following examples show how to load a data file that is already on the filesystem.
```java
CarrierApi carrierApi = new CarrierApi();
// Load data from a file on the class path
carrierApi.loadDataFromClassPath(<data file name on class path>);
// Load data from file path
carrierApi.loadDataFromFile(<data file path>);
```
##### Loading data from an `InputStream` #####
The following examples show how to load a data file from an `InputStream` object.
This can be used if you do not wish to load the data file from the local file system.
```java
CarrierApi carrierApi = new CarrierApi();
InputStream inputStream = <Obtain InputStream>;
carrierApi.loadDataFromStream(inputStream);
```
### Usage ###
The API can be queried by passing any of the following to either the
getProperty() or the getProperties() methods.
1. An IP address string. _e.g. "62.40.34.220", "2405:204:6187:e2e4:d99b:a3be:d3aa:4e00" _
2. A **Map** of HTTP Header names to HTTP Header values. The API will choose the
most appropriate IP address to use.
3. A **HttpServletRequest** object. The API will choose the most appropriate IP
address to use.
### Choosing an IP address ###
If the API is passed either a Map of HTTP Headers or a HttpServletRequest object
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:
```java
String ip = "62.40.34.220";
CarrierApi carrierApi = new CarrierApi();
DataFile dataFile = new DataFile.Builder(<data file download URL>).fileDirectory(<persistent download directory>).buildCarrierDataFile()
carrierApi.downloadAndLoadDataFile(dataFile); // multiple calls will reload the data file each time
// get all properties
Properties props = carrierApi.getProperties(ip);
// .... use the properties ....
if (props.containsKey("networkOperator")) {
Property property = (Property)props.get("networkOperator");
String operatorName = property.asString();
System.out.println("networkOperator: "+operatorName);
}
// get a single property
Property mccProp = carrierApi.getProperty(ip, "mcc");
if (mccProp != null) {
String mcc = mccProp.asString();
System.out.println("MCC: " + mcc);
}
```
### Examples ###
Please see the Examples directory for examples that encompass the following scenarios:
1. **Basic Usage**: Located at Examples/Carrier/basic-usage
2. **Usage within a web application**: Located at Examples/Carrier/web-usage
### 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.Installation.html">Enterprise API Installation</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.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="./Javadoc/index.html">Javadoc</a></li></ul></div>]]>