NAV Navbar
cURL PHP Java Ruby Python

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

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'

<?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)

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()

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'

<?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)

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()

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