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 |
---|---|---|
| Main body text of the mention. Max length is 16k characters | |
| Date associated with the document. Must be a valid ISO-style date string | yyyy-MM-dd['T'HH:mm:ss] |
Optional Fields
Parameter | Definition |
---|---|
| Optional if URL associated with the document (should be unique within data source). Must be a valid URL. |
| Optional if 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. |
| Max length of 200 characters |
| Max length of 200 characters |
|
|
| Must be a valid language code. If this value is not set, then we will attempt to identify it automatically based on the |
|
|
| Max length of 1000 characters |
| Values can be: comment, reply, retweet |
| Max length of 1000 characters |
| Max length of 1000 characters |
| 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. You can use alphanumeric characters and _
in the name(s) of your new custom field(s).
{
"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 over 1 year ago