Brandwatch Developer Hub

Welcome to the Brandwatch developer hub. You'll find comprehensive guides and API documentation to help you start working with Brandwatch as quickly as possible!

Get Started    

Uploading Documents

Upload documents to your new custom data source

Listed below are the required and optional fields needed to upload documents to your new custom data source. A document in this case is a Mention and its metadata, such as the Mention's text, author or date.

๐Ÿšง

"items" array

All of the following required/optional fields for each document are placed within an array called items as seen in the example calls below.

Required Fields

Parameter

Definition

Accepted Values

contents

Main body text of the mention. Max length is 16k characters

date

Date associated with the document. Must be a valid ISO-style date string

yyyy-MM-dd['T'HH:mm:ss]

Optional Fields

Parameter

Definition

url

Optional if guid is supplied, otherwise required.

URL associated with the document (should be unique within data source). Must be a valid URL.

guid

Optional if url is supplied, otherwise required.

User-supplied unique identifier for document (should be unique within data source). Max length of 1k characters. If the guid is re-used, then original document will be replaced. If date is different, but guid is the same, there is some undefined behavior for real-time matching (documents may end up appearing multiple times in a dashboard). Backfilling should fix this issue.

author

Max length of 200 characters

title

Max length of 200 characters

gender

m,f,male or female

language

Must be a valid language code. If this value is not set, then we will attempt to identify it automatically based on the contents field.

geolocation

id: A valid BCR geolocation ID (please contact [email protected] for a list of location IDs)

latitude/longitude: In degrees

zipcode: A valid US zipcode (5 digit number as a string)

parentGuid

Max length of 1000 characters
It can be queried via the engagingWithGuid: operator

engagementType

Values can be: comment, reply, retweet
It can be queried via the engagementType: operator

pageId

Max length of 1000 characters

authorProfileId

Max length of 1000 characters

batch

The identifier for the set of documents being uploaded; it can be specified when uploading new custom documents. If it's not specified, it will be automatically assigned.

Example Call

The following call uploads two documents. The DATA_SOURCE_NUMERIC_ID value comes from the id field we noted when creating a custom data source and is entered in the contentSource field when making this request. You may also upload individual documents to a specific batch (group) of documents by adding the batch id:

curl -X POST 'https://api.brandwatch.com/content/upload' \
-H 'authorization: bearer xxxxxx-xxxxxx-xxxxxx-xxxxxx-xxxx' \
-H 'Content-Type: application/json' \
-d '
{
  "items": [
    {
      "guid": "3d101fd9b2004a11a76ba1ea637eb9f2",
      "gelocation": {
        "id": "USA.fl"
      },
      "date": "2020-03-25T15:04:00",
      "contents": "testing the data upload API",
      "custom": {
        "myfield": "testmetric"
      }
    },
    {
      "guid": "3d101fd9b2004a11a76ba1ea637eb9f3",
      "gelocation": {
        "id": "USA.pa"
      },
      "date": "2020-03-25T15:05:00",
      "contents": "testing the data upload API..again",
      "custom": {
        "npsCategory": "Promoter"
      }
    }
  ],
  "contentSource": 34354220140,
  "batch": "yourBatchIdHere-12345"
}

Here is what the response looks like:

{
    "uploadCount":2,
    "Batch":"yourBatchIdHere-12345"
}

โ—๏ธ

Limits & Usage Reporting

You are limited to uploading 1,000 documents per request. The uploadCount value in the JSON response represents the number of documents you've just uploaded.

There is also a limit to how many documents can be uploaded in a 30 day/24 hour period. There two options to monitor usage which you can find in the article Usage Reporting.

Custom Fields

Each document can have a set of custom fields associated with them. These custom fields are arbitrary key value pairs that you can use to upload your own categorization for the uploaded custom data. They are mostly used for filtering documents (at the query and/or dashboard level), but can also be used in rules and tags. For example, if you upload product reviews data, you can use a custom field to upload the product rating for each uploaded review.

{
  "items": [
    {
      "guid": "...",
      "custom": {
        "myField1": "this is some text",
        "anotherField1": "with some different text"
      }
    },
    {
      "guid": "...",
      "custom": {
        "myField2": "this is some text again",
        "anotherField2": "with some different text again"
      }
    }
  ],
  "contentSource": DATA_SOURCE_NUMERIC_ID
}

To filter your data using custom fields, you can use the custom_CustomFieldName: operator. Replace CustomFieldName with the name of your custom field and add the value of your custom field after the operator as seen in the example below:

custom_NPSCategory:Promoter

โ—๏ธ

Custom Fields Limit

There is a limit of 10 custom fields per data source. As documents are uploaded, the custom fields used are tracked. If the existing field names used and the new field names in an upload would exceed 10, then you will receive an error (HTTP 400) when trying to upload the documents.

Updated about a month ago


What's Next

Once you've uploaded all of your documents to your new custom data source, you must create a query to retrieve this data.

Creating Queries using Custom Data Sources

Uploading Documents


Upload documents to your new custom data source

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.