Using Number Insight via the Nexmo CLI
Overview
You can use the Nexmo CLI to work with the Number Insight API without having to create the requests using curl or by writing program code. This guide shows you how.
Getting Started
Before you begin:
- Sign up for a Nexmo account - this will give you the API key and secret that you will need to access the Number Insight API.
- Install Node.JS - you will use
npm(the Node Package Manager) to install the Nexmo CLI.
Install and Setup the Nexmo CLI (Command Line Interface)
Execute the following command at a terminal prompt to install the Nexmo CLI:
$ npm install -g nexmo-cli
Note: If you do not have sufficient system privileges you might need to prefix the above command with sudo.
Then, provide the Nexmo CLI with your NEXMO_API_KEY and NEXMO_API_SECRET which you can
find on the dashboard getting started page:
$ nexmo setup NEXMO_API_KEY NEXMO_API_SECRET
You only need to do this the first time you use the Nexmo CLI.
Try your own number with the Basic API
The Number Insight Basic API is free to use. Test it with your own number by using nexmo insight:basic (or nexmo ib) and replacing the number shown with your own number. The number must be in international format:
$ nexmo insight:basic 447700900000
The Nexmo CLI displays the number you entered and the country it belongs to:
447700900000 | GB
To see the other details that the response from the Number Insight API contains, use the --verbose switch (or -v for short):
$ nexmo insight:basic --verbose 447700900000
The full response from the Basic API contains the following information:
[status]
0
[status_message]
Success
[request_id]
385bf642-d096-4b85-9dfc-4c1910d65300
[international_format_number]
447700900000
[national_format_number]
07700 900000
[country_code]
GB
[country_code_iso3]
GBR
[country_name]
United Kingdom
[country_prefix]
44
This human-readable output mirrors the field names and data available in the JSON response: it returns data about your request (status, status_message, request_id), details of the country that the number belongs to (country_name, country_prefix etc.) and how to format the number appropriately for that country (national_format_number).
If you do not see a response similar to that shown above, check your API credentials and ensure that you have installed Node.js and nexmo-cli properly.
Test the Standard and Advanced APIs
The Standard and Advanced Number Insight APIs provide even more information about the number including details of the operator and roaming status (for mobile numbers). See the feature comparison table to see the response data that each API level includes.
Note: Calls to the Standard and Advanced APIs are not free, and you will be asked to confirm that you wish to charge your account when you use them.
Using the Number Insight Standard API
To use the Number Insight Standard API, use the nexmo insight:standard command
$ nexmo insight:standard --verbose 447700900000
A typical response from the Standard API looks like this:
[status]
0
[status_message]
Success
[request_id]
aaaaaaaa-bbbb-cccc-dddd-0123456789ab
[international_format_number]
447700900000
[national_format_number]
07700 900000
[country_code]
GB
[country_code_iso3]
GBR
[country_name]
United Kingdom
[country_prefix]
44
[request_price]
0.00500000
[remaining_balance]
1.995
[current_carrier.network_code]
23420
[current_carrier.name]
Hutchison 3G Ltd
[current_carrier.country]
GB
[current_carrier.network_type]
mobile
[original_carrier.network_code]
23410
[original_carrier.name]
Telefonica UK Limited
[original_carrier.country]
GB
[original_carrier.network_type]
mobile
[ported]
assumed_ported
Using the Number Insight Advanced API
To use the Advanced API, use insight:advanced (or ia):
$ nexmo insight:advanced --verbose 447700900000
Look for the following additional fields in the response:
[lookup_outcome]
0
[lookup_outcome_message]
Success
[valid_number]
valid
[reachable]
reachable
[roaming.status]
not_roaming
The [lookup_outcome] and [lookup_outcome_message] fields tell you whether the Advanced API was able to determine the validity ([valid_number]), reachability ([reachable]) and roaming status ([roaming.status]) of the number.