Location API v2019-08-15T14:44:25Z
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
The Location API is used for retrieving information on IP addresses, mobile numbers and other subjects. API keys for including as the x-api-key header in requests can be obtained at https://melroselabs.com. The Location API is part of the Identity and Location service from Melrose Labs.
IP Address Lookup
The geographic location associated with an IP address can be looked-up. This information is typically used when verifying the location of a user of a service to help identify fraudulent activity or to aid with presenting the correct website or content based on the user's location.
Telephone Number Lookup
Mobile and fixed-line telephone numbers can be looked-up using the API in order to determine the country and network for the user's home network and where they are currently located (if not currently on their home network). This information is typically used when optimising routing of voice calls and SMS, however can be used as part of anti-fraud checks and for other purposes.
For a fixed-line telephone number the country and network to which the number belongs is returned by the API. For fixed-line and mobile numbers, the network returned by the API may be the network to which the local numbering authority originally allocated the number, rather than the network which the number may have been ported.
The HTTPS REST API is described below, however an ENUM service will be available in the future.
Base URLs:
Email: Melrose Labs - Technical Support
Authentication
- API Key (api_key)
- Parameter Name: x-api-key, in: header.
IP Addresses
Lookup IP address
Code samples
# You can also use wget
curl -X GET https://api.melroselabs.com/location/ip/{ipaddress} \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.melroselabs.com/location/ip/{ipaddress}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.melroselabs.com/location/ip/{ipaddress}', params={
}, headers = headers)
print r.json()
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.melroselabs.com/location/ip/{ipaddress}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
URL obj = new URL("https://api.melroselabs.com/location/ip/{ipaddress}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.melroselabs.com/location/ip/{ipaddress}',
params: {
}, headers: headers
p JSON.parse(result)
GET /ip/{ipaddress}
Get location information on an IP address
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
ipaddress | path | string | true | IP address |
Example responses
200 Response
{
"subject": "string",
"geo": {
"city": "string",
"country_name": "string",
"country_code": "string",
"continent": "string",
"continent_code": "string",
"latitude": "string",
"longitude": "string",
"timezone": "string",
"weather_code": "string",
"postal_code": "string"
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful IP lookup | LocationIP |
400 | Bad Request | Unsuccessful IP lookup | Error |
Phone Numbers
Lookup telephone number
Code samples
# You can also use wget
curl -X GET https://api.melroselabs.com/location/telno/{telephoneno} \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.melroselabs.com/location/telno/{telephoneno}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.melroselabs.com/location/telno/{telephoneno}', params={
}, headers = headers)
print r.json()
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
'x-api-key' => 'API_KEY',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.melroselabs.com/location/telno/{telephoneno}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
URL obj = new URL("https://api.melroselabs.com/location/telno/{telephoneno}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json',
'x-api-key' => 'API_KEY'
}
result = RestClient.get 'https://api.melroselabs.com/location/telno/{telephoneno}',
params: {
}, headers: headers
p JSON.parse(result)
GET /telno/{telephoneno}
Get location information on a telephone number (mobile or fixed line)
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
telephoneno | path | string | true | Telephone number (mobile or fixed-line) |
Example responses
200 Response
{
"subject": "string",
"number": {
"country": "string",
"ndc": "string",
"subscriber": "string"
},
"geo": {
"country_name": "string",
"country_code": "st",
"continent": "Africa",
"continent_code": "AF"
},
"network": {
"name": "string",
"mccmnc": "string",
"geoHome": {
"country_name": "string",
"country_code": "st",
"continent": "Africa",
"continent_code": "AF"
},
"geoCurrent": {
"country_name": "string",
"country_code": "st",
"continent": "Africa",
"continent_code": "AF"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful telephone number lookup | LocationTelNo |
400 | Bad Request | Unsuccessful lookup of telephone number | ErrorTelNo |
404 | Not Found | Unsuccessful lookup of telephone number (number issue) | ErrorTelNo |
Schemas
LocationTelNo
{
"subject": "string",
"number": {
"country": "string",
"ndc": "string",
"subscriber": "string"
},
"geo": {
"country_name": "string",
"country_code": "st",
"continent": "Africa",
"continent_code": "AF"
},
"network": {
"name": "string",
"mccmnc": "string",
"geoHome": {
"country_name": "string",
"country_code": "st",
"continent": "Africa",
"continent_code": "AF"
},
"geoCurrent": {
"country_name": "string",
"country_code": "st",
"continent": "Africa",
"continent_code": "AF"
}
}
}
LocationTelNo Schema
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
subject | string | true | none | Telephone number |
number | object | true | none | Telephone number split into components |
» country | string | true | none | Country digits |
» ndc | string | false | none | Network prefix digits |
» subscriber | string | false | none | Subscriber digits |
geo | LocationTelNoGeo | false | none | Geographic location based on country code and NDC of telephone number |
network | object | false | none | Network of subscriber |
» name | string | false | none | Name of network |
» mccmnc | string | false | none | MCC-MNC of network |
» geoHome | LocationTelNoGeo | false | none | Geographic information on home network |
» geoCurrent | LocationTelNoGeo | false | none | Geographic information on current network |
ErrorTelNo
{
"message": "OK"
}
ErrorTelNo Schema
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
message | string | true | none | Error string |
Enumerated Values
Property | Value |
---|---|
message | OK |
message | UNKNOWN_SUBSCRIBER |
message | CALL_BARRED |
message | ABSENT_SUBSCRIBER |
message | TIMEOUT |
message | REQUEST_THROTTLED |
message | BLOCKED |
message | FAILURE |
LocationTelNoGeo
{
"country_name": "string",
"country_code": "st",
"continent": "Africa",
"continent_code": "AF"
}
Geographic location
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
country_name | string | false | none | Country ISO 3166/MA (truncated where necessary) |
country_code | string | false | none | Country code ISO 3166-1 |
continent | string | false | none | Continent name |
continent_code | string | false | none | Continent code (AF,AS,EU,NA,SA,AN,OC) |
Enumerated Values
Property | Value |
---|---|
continent | Africa |
continent | Asia |
continent | Europe |
continent | North America |
continent | South America |
continent | Antarctica |
continent | Oceania |
continent_code | AF |
continent_code | AS |
continent_code | EU |
continent_code | NA |
continent_code | SA |
continent_code | AN |
continent_code | OC |
LocationIP
{
"subject": "string",
"geo": {
"city": "string",
"country_name": "string",
"country_code": "string",
"continent": "string",
"continent_code": "string",
"latitude": "string",
"longitude": "string",
"timezone": "string",
"weather_code": "string",
"postal_code": "string"
}
}
LocationIP Schema
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
subject | string | true | none | IP address |
geo | object | false | none | Geographic information for IP address |
» city | string | false | none | City or town |
» country_name | string | false | none | Country |
» country_code | string | false | none | Country code ISO 3166-1 |
» continent | string | false | none | Continent name |
» continent_code | string | false | none | Continent code |
» latitude | string | false | none | Latitude (degrees) |
» longitude | string | false | none | Longitude (degrees) |
» timezone | string | false | none | Timezone |
» weather_code | string | false | none | Code of nearest weather station |
» postal_code | string | false | none | Zip / postal code |
Error
{
"message": "string"
}
Error Schema
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
message | string | true | none | Error message |