Package mobi :: Package mtld :: Package da :: Package carrier :: Module carrier_api :: Class CarrierApi

Class CarrierApi

object --+
         |
        CarrierApi

The main class for the Carrier Detection API. Used to load the data file and perform lookups using IPv4 addresses.

Please note that is advisable to load only a single instance of this class to avoid multiple loadings of the data file.

Example usage:

>>> # Import the DeviceAtlas CarrierApi module.
>>> from mobi.mtld.da.carrier.carrier_api import CarrierApi
>>>
>>> ip = '62.40.34.220'
>>> carrier_api = CarrierApi()
>>> carrier_api.load_data_from_file("/path/to/sample.dat")
>>>
>>> # Get all properties
>>> properties = carrier_api.get_properties(ip)
>>>
>>> # Use the properties
>>> if 'networkOperator' in properties:
>>>     operator_name = str(properties['networkOperator'])
>>>     print("networkOperator: " + operator_name)
>>>
>>> # Get a single property
>>> mcc_property = carrier_api.get_property(ip, 'mcc')
>>>
>>> if mcc_property is not None:
>>>     print("MCC: " + str(mcc_property))

Please see the code in the Examples directory for additional samples.

Author: DeviceAtlas Limited

Instance Methods

load_data_from_file(self, path)
Load the data file from the provided path.

get_data_file_copyright(self)
Returns the data file copyright text.

get_data_file_creation_date(self)
Returns the data file creation date in ISO8601 format.

get_data_file_version(self)
Returns the version of the data file.

Properties, None

get_properties(self, ipv4)
Get the Carrier properties for a given IP address or for a given dictionary of HTTP headers.

Property, None

get_property(self, ipv4, propertyName)
Try to obtain a specific property for a given IP address.

list

get_property_names(self)
A list of all the property names.

str

get_ip(self, keyVals)
Get the most suitable IP address from the given keyVals dictionary of HTTP headers.

property_name_exists(self, propertyName)
Checks if the given propertyName is not None and exists in the data file.

bool

is_public_ip(self, ipv4)
An IP address is considered public if it is not in any of the following ranges:

extract_ip(self, headerName, headerValue)
Extracts and cleans an IP address from the headerValue.

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties
Inherited from `object`: `__class__`

Method Details

load_data_from_file(self, path)

Load the data file from the provided path. The data file is reloaded every time this method is called.

Parameters:

path - The path on disk to the data file.

Raises:

e - DataFileException when there is a problem with the data file.

get_data_file_copyright(self)

Returns the data file copyright text.

Returns:: The copyright.

get_data_file_creation_date(self)

Returns the data file creation date in ISO8601 format.

Returns:: The creation date.

get_data_file_version(self)

Returns the version of the data file.

Returns:: The version of the data file.

get_properties(self, ipv4)

Get the Carrier properties for a given IP address or for a given dictionary of HTTP headers. In case a dictionary is passed, the API will choose the most appropriate IP to use by checking the following headers:

   - X-Forwarded-For
   - Client-Ip
   - X-Client-Ip
   - rlnClientIpAddr
   - Proxy-Client-Ip
   - Wl-Proxy-Client-Ip
   - X-Forwarded
   - Forwarded-For
   - Forwarded

Parameters:

ipv4 - The IP address or a dictionary of HTTP headers {"Client-Ip": "", ...} to find carrier properties for.

Returns: Properties, None

The found properties or None if no properties found.

get_property(self, ipv4, propertyName)

Try to obtain a specific property for a given IP address.

Parameters:

ipv4 - The IP address or a dictionary of HTTP headers {"Client-Ip": "", ...} to find carrier properties for.
propertyName - The name of the property to return.

Returns: Property, None

The property or None if no property found.

Note: If multiple properties are needed for the same IP, it is more efficient to call get_properties() once rather than repeated call to get_property().

get_property_names(self)

A list of all the property names. The list contains PropertyName objects that each have a string name and an associated data type.

Returns: list: A list of property names.

get_ip(self, keyVals)

Get the most suitable IP address from the given keyVals dictionary of HTTP headers.

Parameters:

keyVals - A dictionary of HTTP header name to HTTP header value.

Returns: str

The most suitable IP or None if a suitable IP could not be found.

property_name_exists(self, propertyName)

Checks if the given propertyName is not None and exists in the data file. Calls to this methods must ensure that the data object is already loaded.

Parameters:

propertyName - The name of the property to check.

Raises:

e - InvalidPropertyNameException

is_public_ip(self, ipv4)

An IP address is considered public if it is not in any of the following ranges:

Any local address:
```
   IP: 0
```
A local loopback address:
```
   range: 127/8
```

A site local address:

   range: 10/8
   range: 172.16/12
   range: 192.168/16

A link local address:
```
   range: 169.254/16
```

Parameters:

ipv4 - The IP address to check.

Returns: bool

True, if it is a public IP; False, if the IP is invalid or is not public.

extract_ip(self, headerName, headerValue)

Extracts and cleans an IP address from the headerValue. Some headers such as "X-Forwarded-For" can contain multiple IP addresses such as: clientIP, proxy1, proxy2...

This method splits up the headerValue and takes the most appropriate value as the IP.

Parameters:

headerName - The name of the HTTP header.
headerValue - The value for the the HTTP header.

Returns:

The most suitable IP address or None if no IP is found.