Look up a visitor's location

On this page

Intro A few words on accuracy Prerequisites Retrieving a location Example response Triggering experiences based on a country Further reading

In this article...

We'll take an in-depth look at how you can use our Geolocation API to do a real-time lookup of a user's IP address.

Intro

To deliver geolocation results, Qubit uses a Media Rating Council accredited third-party service called NetAcuity from digitalelement. As with all geolocation services, this uses an Internet Protocol address (IP) as a unique identifier to look up a computer or computer network location.

A few words on accuracy

At its most precise, this method can map an IP address to a house. At its least precise, the same method may only map an address to a country. It is also worth noting that by its very nature, IP geolocation gets progressively less reliable the more precise you look to pinpoint a user's location (country > region > area > city).

When targeting by location, one thing that could help is using "area" instead of "city". The former is less specific and less prone to arbitrary geographic splits.

Please remember that we may incorrectly categorize certain addresses because ISPs route traffic to a single node that isn't always collocated with the user. A good example is that some New York City ISPs show up as New Jersey because of how they route traffic.

WARNING: It is important to understand that using an IP to locate users when serving experiences or segmenting, for example, is not 100% accurate.

Prerequisites

Unique values

Before using the Location API, you will require the following unique values:

<tracking_id> - Qubit Tracking Id for the property the request is made from
<visitor_id> - Unique site Id assigned to the user, generated by the smartserve script on the page and set in the cookies qb_permanent and qbTracker

Retrieving a location

To get the geolocation of the current user, make a GET request to the following URL:

https://orca.qubitproducts.com/ns?cid=<visitor_id>&id=<tracking_id>

Example response

{
  'geo': {
    ip: '86.13.100.143',
    country: 'GB',
    country_string: 'united kingdom',
    region: '25447',
    region_string: 'london',
    metro_area: '826044',
    metro_area_string: 'itv london',
    city: '4782',
    city_string: 'london',
    latitude: '51.5149',
    longitude: '-0.095189'
  }
}

INFO: You can look up the codes returned in the response in our Resources section.

In some instances, the field country may return the value unknown. You can see this in the following example:

{
  'geo': {
    country: 'unknown'
  }
}

Triggering experiences based on a country

For those clients wishing to trigger experiences based on a user's country, we recommend checking explicitly for this value, for example:

module.exports = function triggers (options, cb) {
  if (options.meta.isPreview) {
    cb() // Always run if in preview mode
  } else {
    options.getVisitorState().then(function (visitor) {
      // Only execute if there is a known country that is not the US
      var shouldExecute = visitor && visitor.country && !/unknown|united states/i.test(visitor.country)
      if (shouldExecute) {
        cb() // Run the experience
      }
    })
  }
}