Network lookup API

Introduction

Our network lookup API can provide you with a more detailed response for your network lookups, including an indication of how the information was discovered, by sending a request via HTTP POST to our gateway, allowing quick integration with your own services.

Identify which network is providing services to a mobile handset

Two classes of network lookup service make it possible to identify the network operator for a given mobile number.

Pricing

Service Cost per query
OFCOM reservation reference Free
Network reference 1 SMS credit

OFCOM reservation reference service

OFCOM publish information about which mobile numbers were reserved for which provider. We provide a way for you to refer to this information programmatically for free.

Please note that where a number has been ported from one provider to another, the system will inform you of the original provider rather than the current one. This is the same regardless of the different methods used to access the data.


How to identify the network provider for a given mobile number

Send a HTTP post request to either of the following gateways:

http://gw.aql.com/nl/network_lookup.php (or https)

including these variables in your request (* denotes a required field):

username *
password *
msisdn * How should my number be formatted?
method: 1, 2 or 3 (bitmask)
method=1 : for Ofcom only lookup (Free)
method=2 : for network lookup (cost -1 premium(UK) or -1 premium(Global) credit) method=3 : (1+2) for both Ofcom and Network Lookup contact: 0 (zero) or 1 (one) (1 to include contact details, 0 for no details)


Possible return values

contact: Network provider contact details.
country: Country
msisdn: The mobile telephone number
nl_accuracy:

1: Live data
2: Cached within 24 hours
3: Cached information (up to 1 month old)
4: Prefix identification
9: Failed

nl_mvno: Name of Mobile Virtual Network Operator
nl_network: Network name (Network Lookup)
nl_network_code: MCC+MNC code (if nl_network undecipherable – Network Lookup)
nl_location: The current location that the SIM is registered
ofcom_area: Geographic number area code (Ofcom database)
ofcom_change_date: Date when the data last changed (Ofcom database)
ofcom_network: Network name (Ofcom database)
ofcom_tariff_note: Tariff note according to Ofcom (Ofcom database)
ofcom_use: Number usage according to Ofcom (Ofcom database)
sms_handler: The party that handles inbound SMS on the number


Example successful lookup responses

Either:
0: Successful lookup
msisdn: 44777XXXXXXX
country: United Kingdom
ofcom_network: Vodafone Ltd
ofcom_change_date: 01-1998
ofcom_use: Mobile services
nl_network: Vodafone Ltd
nl_location: United Kingdom
nl_accuracy: 1

OR with contact
0: Successful lookup
msisdn: 44777XXXXXXX
contact: 08700746464, Vodafone Head Office, The Courtyard, 2-4 London Road, Newbury, Berkshire, RG14 1JX
country: United Kingdom
ofcom_network: Vodafone Ltd
ofcom_change_date: 01-1998
ofcom_use: Mobile services
nl_network: Vodafone Ltd
nl_location: United Kingdom
nl_accuracy: 1

OR international number
0: Successful lookup
msisdn: 491511XXXXXXX
country: Germany
nl_network: T-Mobile Deutschland GmbH
nl_location: Federal Republic of Germany
nl_accuracy: 1

OR UK landline
0: Successful lookup
msisdn: 44120XXXXXXX
contact: 08702257879, BT plc, 81 Newgate Street, London, EC1A 7AJ
country: United Kingdom
ofcom_area: Colchester
ofcom_network: BT
ofcom_change_date: 07-1994


Error responses

Any failed queries will return an error response:
“status # : description”
e.g.: 2: Authentication error

Status Description
0 0: Successful lookup
1: Insufficient route Can appear when querying a foreign destination
2: Authentication error Incorrect username or password
3: MSISDN number error Incorrect MSISDN provided
4: Insufficient credit Buy more credit
5: Internal system error There was a problem with processing your request Please report this using our support system
9: Undefined error Error without any specific description Please report this using our support system
10: Gateway unreachable Desired network was not reachable
11: Result not parsable Data was not returned in expected format
12: Data unavailable HLR data unavailable for the MSISDN
13: Unknown subscriber MSISDN is not known to the network
14: Absent subscriber MSISDN is not currently registered to any network
15: Invalid request Unexpected data was submitted to a network
16: System failure Request rejected due to network or protocol failure
17: Lookup not supported MSISDN does not support look ups
18: Request rejected MSISDN is barred
19: Request aborted Indicates temporary problem or lost reach
20: Timeout No response was received from a network

Network lookup

Following the link below will take you to our on-site Network Lookup service where you can identify the operator for a particular mobile or landline number, based on existing OFCOM information. Network Lookup Service.