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 query parameters needed to upload documents to your new custom data source:

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.

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",
      "anotherField": "with some different text"
      }
    }
  ],
  "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.

Example Call

The following call uploads one document. The DATA_SOURCE_NUMERIC_ID value from the id field we noted when creating a custom data source is entered in the contentSource field when making the request, as seen below:

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..again",
      "custom": {
        "myfield": "testmetric"
      }
    }
  ],
  "contentSource": 34354220140
}'

Here is what the response looks like:

{
    "uploadCount":2,
    "Batch":"4f4ef276-84b1-47bf-abad-29fc08a183c4"
}

❗️

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:

Usage reporting in upload request response

We’ve included an extra JSON property requestUsage: True when making the request to upload documents to trigger extra fields in the response when you are finished uploading documents. Here is an example:

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..again",
      "custom": {
        "myfield": "testmetric"
      }
    }
  ],
  "contentSource": 34354220140,
  "requestUsage": true
}'
{
        "uploadCount": "...",
        "batch": "...",
        "monthlyDocumentsUploaded": 501,
        "monthlyDocumentsUploadLimit": 1000
}

Usage reporting endpoint

In addition to requesting usage numbers with the upload request, there is also a dedicated endpoint to retrieve usage numbers. This can be useful if you want to confirm there is enough spare upload capacity before actually uploading documents. Here is an example call:

curl -x GET 'https://api.brandwatch.com/content/upload/usage' \
-H 'authorization: bearer xxxxxx-xxxxxx-xxxxxx-xxxxxx-xxxx' \
{
  "monthlyDocumentsUploaded": 0,
  "monthlyDocumentsUploadLimit": 1000
}

Updated a day 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.