Look up visitor location

This is for:

Developer

In this article

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.

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.

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:

Name Description

Name	Description
`<tracking_id>`	CEH tracking ID for the property the request is made from. This will be provided by your Customer Success manager at Coveo.
`<visitor_id>`	Unique site visitor ID, generated by the Smartserve script on the page and is set in the cookies qb_permanent and qbTracker.

<tracking_id>

CEH tracking ID for the property the request is made from. This will be provided by your Customer Success manager at Coveo.

<visitor_id>

Unique site visitor ID, generated by the Smartserve script on the page and is 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'
  }
}

Note

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's 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
      }
    })
  }
}