Monitors API Documentation

The Monitors API is a RESTful JSON API intended to be used by clients of Nuvi who have special use cases for creating, pausing and deleting monitors programmatically. The API is not intended to be a replacement for Nuvi’s web interface or Nuvi Hub’s database access but is aimed to facilitate programmatic management of monitors. The Monitors API can be accessed at the following domain:https://api.nuvi.com

Authentication

The Monitors API uses HTTP Basic authentication on every request. You may use any valid username and password associated with your Nuvi account to authenticate. HTTP Basic authentication requires you to add the Authentication header to every request. The value of that header should include the keyword “Basic”, followed by a space, followed by your username and password separated by a colon and encoded in base64.

Example:

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

(username:password base64 encoded becomes dXNlcm5hbWU6cGFzc3dvcmQ=)

Many endpoints in the API require you to have your company GUID. Your Client Success Manager will be able to provide that information to you.

Usage

Retrieve a single monitor

Returns a monitor definitionGET /v1/companies/:company_guid/social_monitors/:guid

Example response:

{ "guid": "8efadc55-4618-4df8-bd78-3b2ef4d4795c", "name": "My Monitor", "companyGuid": "CMPY-7ea99d92-5aaa-4315-8357-2907f5225588", "status": "active", "rule": "test AND monitor" }

List all monitors

Returns an array containing all the monitor definitions for the companyGET /v1/companies/:company_guid/social_monitors

Example response:

[{ "guid": "8efadc55-4618-4df8-bd78-3b2ef4d4795c", "name": "My Monitor", "companyGuid": "CMPY-7ea99d92-5aaa-4315-8357-2907f5225588", "status": "active", "rule": "test AND monitor" },{ "guid": "276adca5-46a9-5dfb-ad7c-221e98d479d6", "name": "My Second Monitor", "companyGuid": "CMPY-7ea99d92-5aaa-4315-8357-2907f5225588", "status": "active", "rule": "test AND monitor AND nuvi" }]

Create a monitor

Creates a new monitor with the given rules and starts collecting mentions immediately. Responds with a standard monitor definition object.

rule is defined in NQL (Nuvi Query Language) and contains the keywords and other logic used to match and ingest online content. More information about NQL is provided at the end of this document.

status can either be "active" or "paused_by_user"

POST /v1/companies/:company_guid/social_monitors

Example POST body

{ "name": "My First Monitor", "rule": "test AND monitor", "status": "active" }

Update a monitor

Update the NQL rules, name or status of a monitor. Responds with a standard monitor definition object.PUT /v1/companies/:company_guid/social_monitors/:guid

Example PUT body

{ "name": "My Updated Monitor", "rule": "test AND monitor AND happiness", "status": "paused_by_user" }

Delete a monitor

Delete the monitor entirely. This endpoint will stop the data collection process and delete the monitor definition and all mentions associated with it. Responds with HTTP 200 and no content.DELETE /v1/companies/:company_guid/social_monitors/:guid

NUVI Query Language (NQL)

NUVI Query Language (NQL**) is an original, domain specific language (DSL) created at NUVI.

We designed it to be a concise and efficient way to create and read complex rules used to filter and sort text-based data, specifically in regards to social media posts.

The structure was designed for large and small **rules sets** which typically have long lists of **values** and conditionals used to match specific Natural Language-based data, like social media posts.

Structure

A rule consists of the following arguments:[field] [operator] [value(s)] [connector*]*Connector is optional and not used in simple rules

Example 1 - Simple Rule

Find all mentions that include the word football or baseball.word ANY football, baseball

Example 2 - Simple Rule with Connector

Find all mentions that include the word football OR baseball but IGNORE mentions that include the work basketballword ANY football, baseball AND word NOT ANY basketball

Example 3 - Complex Rule with Multiple Connectors

Find mentions that **include the word holiday** but **ignores birthday mentions including words democratic republican**. We also want to make sure we are only tracking mention written in English and within a specified geographic region. The rule definition would look like this:word ANY happy birthday AND word NOT_ANY birthday, democratic, republican AND language ANY en, sp AND coordinate ANY (-105.27346517 40.01924738 16093.4), (-155.27346517 45.01924738 8046.7)Rules are designed to be chained together and are separated by the presence of a connector. Arguments are parsed by the use of their corresponding reserved words.

Arguments

Field Argument Options