Quickstart Guide

IP Locator

Introduction

This document details how to quickly access IP Locator.

IP Locator can be used to:

  • Verify an IP address as valid.
  • Associate a physical location with an IP address.
  • Determine the location of a mobile phone’s IP address.
  • Determine connection speed and type of an IP address.
  • Determine the Internet Service Provider of an IP address.
  • Detect proxies and return their type.

Basic Order of Operations

Real Time

  • Put the contact data into JSON, XML, or REST format.
  • Put the input address into JSON, XML, or REST format.
  • Make sure to include your license key.
  • Specify any options you would like to modify from their default
  • Send the request to the service URL: https://globalip.melissadata.net/v4/WEB/iplocation/doiplocation using HTTP GET
  • Receive the result back from the service

Batch

  • Put the input request together using JSON or XML. Put up to 100 records into the request array.
  • Make sure to include your license key.
  • Specify any options you would like to modify from their default. They will apply to all records in the request.
  • Make sure to specify the same options for all records in the batch to maintain consistency.
  • Send the full request to the service URL: https://globalip.melissadata.net/v4/WEB/iplocation/doiplocation using HTTP POST
  • Receive the result back for all addresses from the input

Input Request

NOTE: It expects UTF-8 character encoding. Be on the lookout for question marks (?), squares (▖) or other weird characters like �. They may be an indication of encoding issues and may result in data loss. Bad encoding or character loss is not something our service can correct for you.

Real Time

With a REST request, you can include all the input along with the URL for an easy and quick way of sending a single record.

C:\>curl -X GET "https://globalip.melissadata.net/v4/WEB/iplocation/doiplocation?id=########&t=CurlExample&opt=&ip=216.231.3.166"

You can also put the URL without the "curl -X GET" command directly into your browser. You can also toggle between getting XML or JSON back using the format input parameter. As you can see, in this example, we are asking for JSON back.

Batch

Batch requests from 1 to 100 records at a time are sent using HTTP POST. This means you cannot send it in a browser like with HTTP GET.

Header

Make sure the header includes this line.

Accept: application/json

Body

{
  "CustomerID":"LICENSE_KEY",
  "TransmissionReference":"ipbatch",
  "Records":[
    {
      "RecordID":"1",
      "IPAddress":"216.231.3.166"
    },
    {
      "RecordID":"2",
      "IPAddress":"10.10.10.1"
    },
    {
      "RecordID":"100",
      "IPAddress":"120.40.140.11"
    }
  ]
}

Input Fields

Batch Input REST Input Description REQUIRED
TransmissionReference t Value passed through unchanged to the response for identification or any other purpose. No
CustomerID id The License Key issued by Melissa. Yes
IPAddress ip The IP Address to verify. Yes
Cols cols Specify what domain information to return. No

Output Response

Real Time

Here is a sample response of the real-time request from above.

{
  "Version": "5.0.0.15",
  "TransmissionReference": "CurlExample",
  "TransmissionResults": "",
  "Records": [
   {
     "City": "Newport Beach",
     "ConnectionSpeed": "broadband",
     "ConnectionType": "wifi",
     "Continent": "North America",
     "CountryAbbreviation": "US",
     "CountryName": "United States",
     "DomainAddress1": " ",
     "DomainAdministrativeArea": "California",
     "DomainAgeEstimated": "7498",
     "DomainAvailability": "UNAVAILABLE",
     "DomainCountry": "United States",
     "DomainCountryCode": "US",
     "DomainCreatedDate": "2000-10-16T13:48:37",
     "DomainEmail": " ",
     "DomainExpirationDate": "2021-10-16T13:48:36",
     "DomainLocality": " ",
     "DomainName": "melissadata.com",
     "DomainOrganization": "Melissa Data Corp",
     "DomainPostalCode": " ",
     "DomainPrivateProxy": " ",
     "DomainUpdatedDate": "2020-10-17T03:20:46",
     "DST": "Y",
     "IPAddress": "216.231.3.166",
     "ISPName": "Cox Communications Inc.",
     "Latitude": "33.630000",
     "Longitude": "-117.870000",
     "PostalCode": "92660",
     "ProxyDescription": " ",
     "ProxyType": " ",
     "RecordID": "1",
     "Region": "California",
     "Result": "IS01",
     "TimeZoneCode": "PST",
     "TimeZoneName": "Pacific Standard Time",
     "UTC": "-08:00"
    }
  ]
}

Batch

Here is a sample response of the sample batch request.

{
    "Version": "5.0.0.15",
  "TransmissionReference": "ipbatch",
  "TransmissionResults": "",
  "Records": [
    {
     "City": "Newport Beach",
     "ConnectionSpeed": "broadband",
     "ConnectionType": "wifi",
     "Continent": "North America",
     "CountryAbbreviation": "US",
     "CountryName": "United States",
     "DomainAddress1": " ",
     "DomainAdministrativeArea": "California",
     "DomainAgeEstimated": "7498",
     "DomainAvailability": "UNAVAILABLE",
     "DomainCountry": "United States",
     "DomainCountryCode": "US",
     "DomainCreatedDate": "2000-10-16T13:48:37",
     "DomainEmail": " ",
     "DomainExpirationDate": "2021-10-16T13:48:36",
     "DomainLocality": " ",
     "DomainName": "melissadata.com",
     "DomainOrganization": "Melissa Data Corp",
     "DomainPostalCode": " ",
     "DomainPrivateProxy": " ",
     "DomainUpdatedDate": "2020-10-17T03:20:46",
     "DST": "Y",
     "IPAddress": "216.231.3.166",
     "ISPName": "Cox Communications Inc.",
     "Latitude": "33.630000",
     "Longitude": "-117.870000",
     "PostalCode": "92660",
     "ProxyDescription": " ",
     "ProxyType": " ",
     "RecordID": "1",
     "Region": "California",
     "Result": "IS01",
     "TimeZoneCode": "PST",
     "TimeZoneName": "Pacific Standard Time",
     "UTC": "-08:00"
    },
    {
     "City": "Private",
     "ConnectionSpeed": "broadband",
     "ConnectionType": "wired",
     "Continent": " ",
     "CountryAbbreviation": " ",
     "CountryName": "Reserved/Private",
     "DomainAddress1": " ",
     "DomainAdministrativeArea": " ",
     "DomainAgeEstimated": " ",
     "DomainAvailability": " ",
     "DomainCountry": " ",
     "DomainCountryCode": " ",
     "DomainCreatedDate": " ",
     "DomainEmail": " ",
     "DomainExpirationDate": " ",
     "DomainLocality": " ",
     "DomainName": " ",
     "DomainOrganization": " ",
     "DomainPostalCode": " ",
     "DomainPrivateProxy": " ",
     "DomainUpdatedDate": " ",
     "DST": "N",
     "IPAddress": "10.10.10.1",
     "ISPName": " ",
     "Latitude": "0.000000",
     "Longitude": "0.000000",
     "PostalCode": "0",
     "ProxyDescription": " ",
     "ProxyType": " ",
     "RecordID": "1",
     "Region": "Reserved/Private",
     "Result": "IS01",
     "TimeZoneCode": " ",
     "TimeZoneName": " ",
     "UTC": " "
    },
    {
     "City": "Putian",
     "ConnectionSpeed": "broadband",
     "ConnectionType": "wired",
     "Continent": "Asia",
     "CountryAbbreviation": "CN",
     "CountryName": "China",
     "DomainName": "163data.com.cn",
     "DST": "N",
     "IPAddress": "120.40.140.11",
     "ISPName": "Chinanet Fujian Province Network",
     "Latitude": "25.450000",
     "Longitude": "119.020000",
     "PostalCode": "351100",
     "ProxyDescription": " ",
     "ProxyType": " ",
     "RecordID": "1",
     "Region": "Beijing",
     "Result": "IS01",
     "TimeZoneCode": "CST",
     "TimeZoneName": "China Standard Time",
     "UTC": "+08:00"
    }
  ]
}

Output Fields

Response (Base Level)

Output Name Description
Version The current service version
Transmission Reference Optional request identifier
Transmission Results Service and General Transmission Errors

Record Level

Output Name Description
City The city where the IP address is located.
Connection Speed The connection speed associated with this IP address.
Connection Type The type of connection used by this IP address.
Continent The continent where the IP address is located.
Country Abbreviation The alpha-2 country code of the country where the IP address is located.
Country Name The full name of the country where the IP address is located.
DomainAddress1 The Physical Address associated with the domain.
DomainAdministrativeArea The State or most common geographic data element associated with the domain.
DomainAgeEstimated How long the domain has existed since it's creation.
DomainAvailability Status whether domain is available or unavailable.
DomainCountry The full name of the country associated with the domain.
DomainCountryCode The two character code for the country associated with the domain.
DomainCreatedDate The Created Date of the domain.
DomainEmail The email associated with the domain.
DomainExpirationDate The expiration date of the domain.
DomainLocality The City or most common population center associated with the domain.
Domain Name The domain name associated with the IP address.
DomainOrganization The Organization associated with the domain.
DomainPostalCode The Postal Code associated with the domain.
DomainPrivateProxy The Private Proxy associated with the domain.
DomainUpdateDate The last time the domain was updated.
DST Daylight Savings Time
IP Address The IP Address being looked up
ISP Name The name of the Internet Service Provider.
Latitude The latitude for the IP address.
Longitude The longitude for the IP address.
Postal Code The postal code where the IP address is located.
Proxy Description Additional Details for the Proxy Type returned.
Proxy Type The type of proxy for an IP Address
Record ID ID of each input record
Region The region where the IP address is located
Result A comma delimited string that provides more information from the service.
Time Zone Code The time zone code where the IP address is located.
Time Zone Name The time zone name where the IP address is located.
UTC The GMT offset for the area where the IP address is located.

Interpreting Results

IP Locator and other Melissa APIs will have a Results Output. Several different Result Codes may be returned by the service in order to give you detailed information about the status of the record submitted.

It is important to understand these result codes in order for you to make a determination of good vs bad data and how you would want to use it.

Code Description Recommendation
IS01 The IP Address was found in the database. Good
IS02 The IP Address was not found. Bad
IS03 The IP Address is a proxy. Good
IS04 The IP Address entered is in the IPv6 Format. Good
IE** Results that begin with IE are an indication of an ip error Bad
IC** Results that begin with IC are changes to the input IP Medium

Common Transmission Errors

For a list of the common transmission errors, see the General Info - Response Level Errors page.

For the full list of all possible result codes, please visit our Result Wiki page at IP Locator Result Code Details.