Quick Start Guide

A complementary guide for developers on getting up to speed with the Pulsar API. Please note that this guide is not a replacement for the documentation, it is meant to complement the documentation.

Introduction

Pulsar offers a several different endpoints for our API:

1. data.pulsarplatform.com/trac/graphql the v2 endpoint for obtaining data from TRAC searches

2. trac.pulsarplatform.com/graphql the v2 endpoint for obtaining metadata regarding TRAC searches and the entire TRAC tool for a subdomain

3. data.pulsarplatform.com/graphql/core the v2 endpoint for obtaining data from CORE brandsets

4. interaction-pusher.pulsarplatform.com/graphql the v2 endpoint for pushing first party data onto TRAC searches

Who this guide is for

This quick start guide is designed to help developers get started with the Pulsar API and assumes that the reader is familiar with how APIs work, with some assistance for those new to GraphQL APIs. This document complements, but does not replace the referenced API documentation. It is recommended that the reader reads the API documentation in full, in addition to this guide as most FAQs are included in the API documentation.

What data is available via the GraphQL API?

As a rule of thumb, only data that has been indexed on TRAC or CORE is available via the GraphQL API. So please do not make a like-for-like comparison with the various social media and online platforms that we collect data from. In addition to this, there are some data limitations with some of our data sources. For example, whilst we index a lot of author fields about a Twitter user on TRAC, we are prohibited from sharing some of this information via the API. We advise that you familiarise yourself with these limitations before planning your integration with the Pulsar GraphQL API.

Once you have access to Pulsar platform & your bearer token, you will be able to view the GraphQL schema, which shows you what data fields & types there are. This is an important distinction from how REST endpoints are documented.

New to GraphQL

GraphQL may seem a little strange if you’re coming from a REST background, so we’ve put together a few guides that can help you get up to speed quickly. We highly recommend starting small, and once you get the hang of it, it can be a really powerful tool & a valuable skill set for a developer to have. Follow the steps below to start your GraphQL journey:

1. REST vs GraphQL APIs

2. Intro to Queries (pulling data) & Mutations (pushing data)

3. Intro to Schemas & Types

4. Explore your instance of the Pulsar platform. The strategy used in querying the API is dependent on one's understanding of the data points & insights within the platform. Generally, you need to know what data you wish to pull/push, then structure a query that produces the desired results.

5. Intro to GraphQL query building in under 10 minutes using GraphiQL and/or any public endpoint. Play around with queries until you’re comfortable. You can also download a GraphQL API client such as Insomnia which will be helpful when making queries to Pulsar's APIs.

6. Learn more GraphQL, see various implementations to build your GraphQL confidence

Getting started checklist

• Read the docs - our API docs cover everything you need to know about GraphQL especially if you come from a REST API background. This includes API specific limitations, the difference between REST & GraphQL APIs and sample queries & mutations.

• Discuss your use-case with your Account Manager - data sources behave differently and may have unique constraints that would affect how you structure your queries.

• If you’re new to GraphQL, work through the New to GraphQL section.

• Download a GraphQL API client such as Insomnia to test out your bearer token & make sample calls to the desired endpoints. Here’s a handy guide on using Insomnia. You’ll need to input the following:

  • Endpoint URL - decide which endpoints you need to use.

  • Bearer token - you can get this from your account manager for API enabled users. If the token expires or does not work, your account manager can generate a new one for you.

  • GraphQL query/mutation - the query body is sent via HTTP POST and defines both which field you’re querying, and which output fields will be returned in the response

  • Query variables - this is where you specify query parameters including date range, brand & profile IDs, and mathematical functions such as “COUNT” or “SUM” for producing aggregate metrics over time

• Explore the schema via an API client like Insomnia - you will be able to search for any fields you’re interested in via the built-in documentation browser. This is your primary reference for building queries. Check out the video below on how to do this in Insomnia, if you choose to use it. If you do not wish to use this, a traditional introspection query should work as well

Getting a new API token

Please reach out to your account manager if you need a new API token generated for an API enabled Pulsar user account.

Getting support

You can discuss details of your use-case with your Account Manager who will help you understand what is available from Pulsar. We provide technical support for queries only. If you require technical support, then please submit the full query and response, including any error codes in txt format via the in-app chat function available when you’re logged into Pulsar.