Manage Geosets

Learn how to manage geosets with the Cuebiq API.

Prerequisites

In order to create campaigns you need a token and refresh token request. To get these tokens, you will need to request access to the API. Once access has been approved, Cuebiq will provide a client_id and client_secret as well as a customerId. A token will allow you to call every available endpoint in the Clara API.

Overview

A geoset represents a group of POIs (ex. stores) for which visitation will be measured during a campaign. Geosets are associated with campaigns and there can only be 1 geoset per campaign. A valid customerId is necessary to access existing geosets associated with your account, or to create a new geoset. The geoset endpoints can be called to retrieve a specific geoset, search for a geoset or create a new geoset.

Retrieving a list geosets associated with a customer ID

Get the list of geosest associated with a customerID by calling the following endpoint with a valid customerId path parameter:

 GET   /v1/customers/{customerId}/geosets

See the endpoint documentation for more information and a sample request and response.

Search for a specific geoset by ID

Retrieve a specific geoset by its id by calling the following endpoint with a valid customerId and geosetId path parameters:

 GET   /v1/customers/{customerId}/geosets/{geosetId}

 

See the endpoint documentation for more information and a sample request and response.

Create a new geoset

There are two methods for inserting geoset data:

Method 1 – manually insert geoset data

Method 2 – insert geoset data via Amazon S3 using a pre-signed URL

Method 1 – insert a new geoset with brand information from a file

Use this method to insert geoset data one API call at a time.

Insert new geoset data by calling the following endpoint with a valid customerId path parameter:

 POST   /v1/customers/{customerId}/geosets

Insert Geoset Parameters

 

Method 2 – insert geoset data via Amazon S3 using a pre-signed URL

Use this method to batch insert geoset data by uploading a POI file to an Amazon S3 pre-signed URL.

 

Step 1 – Generate an AWS pre-signed URL by calling the following endpoint with a valid customerId path parameter:

 

 POST   /v1/customers/{customerId}/geosets/upload-urls

 

A successful response from this endpoint will return a presignedUrl and an objectUrl

 

Step 2 – After calling this endpoint, upload your POI file to the presignedUrl then use method 1 to insert new geoset data and pass the objectUrl in as the placesFileLocation property.

Confirming a POI within a geoset

After inserting geoset data using method 1 or method 2, you can look up specific places to confirm the presence of POI data.

 Retrieve place data for a POI by calling the following endpoint with a valid customerId and geosetId path parameter:

 GET   /v1/customers/{customerId}/geosets/{geosetId}/places

See the endpoint documentation for more information and a sample request and response.

Need More Help?

Can’t find an answer or having an issue with the API? Visit our FAQ or request support for more help.