Use imported data

This is for:

Developer

The Import API offers a powerful and flexible solution for leveraging data imported into the Qubit platform to deliver one-to-few and one-to-one personalizations that target smaller sub-sets of visitors, and even individual visitors based on individual behavioral patterns and interactions.

One of the most powerful features of the API is that it provides an endpoint that can be directly called in an experience to target visitors. It supports complex data types and per- field filtering.

The API can be used to fetch any record that has been ingested via the manual or programmatic batch upload methods or Derived dataset, and shares the schema with the dataset. Records are retrieved by providing an <id>, or a list of them, which is looked up against the ingested data’s primary key field.

Note

Currently, the API is read only over HTTP. If you’re using gRPC within your business and are interested in using it with this API please reach out to your Customer Success Manager at Qubit.

Prerequisites

Unique values

Before using the Import API, you’ll require the following unique values:

Name Description

<namespace>

This is also know as the tracking Id for your property the request is made from. You can get this from the Info panel in the Details tab for your import

Retrieving a record

Getting a value in the Import API is made via a GET request.

GET https://datasets.qubit.com/v1/owners/<namespace>/datasets/<import_id>/data?id=<id>&streaming=<streaming>

Where:

  • namespace is your tracking Id. It can be found in the Info card in the Details tab for your import or Derived Dataset, as shown in the following example:

    namespace

  • <import_id> is your Import Id, as shown in the Info card for your import or Derived Dataset. In the following example, we can see the Id that should be passed into the request is testimport:

    Info panel

and where:

  • <id> is key of the record being looked up

  • <streaming> should be replaced with true to return a stream of JSONLines, or false to return a JSON object

If the key exists, the response will the JSON object of the record found.

If the key doesn’t exist, then the request will result in a 200, but will contain a payload as follows:

{
  failure: {
    message: [ '5: Record(s) not found' ]
  },
  httpCode: 404
}

Retrieving multiple values

It’s possible to retrieve multiple values at once by issuing a POST request to the same endpoint. You do this by sending an array of Ids as strings to fetch in the payload:

POST https://datasets.qubit.com/v1/owners/<namespace>/datasets/<import_id>/data?streaming=<streaming>
{
  'ids': ['<id1>', '<id2>', '<id3>', /* .... */]
}

Where:

  • namespace is your tracking Id

  • <import_id> is your Import Id

  • <id> is list of record Ids to retrieve

  • <streaming> should be replaced with true to return a stream of JSONLines, or false to return a JSON object

If at least one of the Ids exists, the response will be a JSON Lines list of the records or, if streaming=false, a JSON array of objects. Non-matching Ids aren’t returned.

If none of the Ids exist, the request will result in a 200, but will contain a payload as follows:

{
  failure: {
    message: [ '5: Record(s) not found' ]
  },
  httpCode: 404
}

Filtering fields

An additional parameter called columns can be provided to filter the fields that will be returned. For example, if a record was stored in the demo import, as shown in the following example:

{
  visitor_id: 1,
  first_name: 'Joyce',
  last_purchase: '2017-03-05 13:17:33',
  registered_on: '2009-07-01 20:51:32',
  customer_segment: 'silver',
  do_not_contact: false
}

then the following request would only return first_name and do_not_contact fields for a record matching the Id of 1

GET https://datasets.qubit.com/v1/owners/<tracking_id>/datasets/demo/data?id=1&streaming=false&col=first_name&col=do_not_contact

or the multiple mode:

POST https://datasets.qubit.com/v1/owners/<tracking_id>/datasets/demo/data?streaming=false
{
  ids: [ '1', '2' ],
  columns: [ 'first_name', 'do_not_contact' ]
}

JavaScript module

A Qubit module, @qubit/datasets, is available when retrieving values from the Import API inside of an experience. This handles all the formatting and parsing of requests and can be used as follow:

var getDatasets = require('@qubit/datasets')

var options = {
  namespace: 'tracking_id'
}

var datasets = getDatasets(options)

datasets.get('demoDataset', 'test')
// resolves with an array of records from 'demoDataset' with Id = 'test'

datasets.get('demoDataset', [ 'test', 'test2' ])
// resolves with an array of records in 'demoDataset' with matching Ids

datasets.get('demoDataset', [ 'test', 'test2' ], [ 'field1', 'field2' ])
// only return 'field1' & 'field2' from the records

// Example handling of a response
datasets.get('demoDataset', 'test').then((result) => {
  console.log(result)
}).catch((e)=>{
  console.log('not found or some other error')
})
Note

There’s a limit of 256 Ids per request.