Documentation - BrandVantage

Introduction

The BrandVantage API provides access to the core data systems that power the platform.

To get started using it, you need to register and create an Organization, selecting one of our plans.

Authentication & Access

To access the BrandVantage API, you must have a valid API key for your Organization. You can view and manage your API keys in your Organization setings.

Every valid API request is deducted from your monthly quota, which resets on the 1st of every month (UTC-0). When your quota expires, you will no longer be able to make any requests to the API. If you need additional quota, please upgrade your Organization's plan to the next tier.

Additionally, the BrandVantage API employs rate limiting to prevent abuse. Each request returns X-Rate-Limit-* headers that provide information about the current state of rate limiting on your requests. As a rule of thumb, it is recommended to not exceed one request per second except where needed in short bursts.

API Errors

A successful call to the API will return a HTTP 200 status along with the result for that specific API. When an error occurs, an RFC 7807 "Problem Details" JSON object is returned along with any additional details available. Errors with the same HTTP Status code can be identified by checking the RFC 7807 Type in the error response.

If you encounter any of these errors, make sure to view the full response to determine the cause and your course of action.

Errors

Validation Error HTTP 400

https://app.brandvantage.co/api-problem/validation-error

There are validation errors in your request that need to be addressed. View the response body for more information about the error. Requests with this error do not count to your quota.

Over Quota HTTP 403

https://app.brandvantage.co/api-problem/over-quota

Each plan has a set quota per month. Please upgrade your plan if you need a higher quota.

Too Many Requests HTTP 429

https://app.brandvantage.co/api-problem/too-many-requests

The API is rate limited to prevent abuse. Requests with this error do not count to your quota.

API Timeout HTTP 500

https://app.brandvantage.co/api-problem/api-timeout

The API uses a timeout to ensure adequate performance for all users. Each request has up to 10 seconds to complete its action before it timesout. Requests with this error count to your quota.

Processing Error HTTP 500

https://app.brandvantage.co/api-problem/processing-error

A miscellaneous processing error during the request. Details about the processing error can be found in the response body. Some API endpoints have expected processing errors, check the Notes section for the specific API. Requests with this error may count to your quota.

Validation Error Response

{
  "errors": {
    "url": [
      "Invalid URL format"
    ]
  },
  "type": "https://app.brandvantage.co/api-problem/validation-error",
  "title": "Validation Error",
  "status": 400,
  "traceId": "0HM9NIJTKU99A:00000002"
}

Processing Error Response

{
  "type": "https://app.brandvantage.co/api-problem/processing-error",
  "title": "Processing Error",
  "detail": "Unable to resolve hostname for remote server",
  "status": 500,
  "traceId": "0HM9NIJTKU99C:00000002"
}

Web Page API

Turning ordinary HTML pages to WebPage Schema objects

Parameters

apiKey

Your API Key

Notes

The WebPage API uses multiple methods, including meta and social tags, microdata and JSON+LD, to identify and set various properties on a WebPage Schema object. Each property may have zero (not returned), one (a single value) or many values (an array) depending on the ability to de-duplicate the data from the target URL. Different properties may support multiple types too as per the specifications on Schema.org and which type is returned will depend on the markup of the target URL.

There is no guarantee about the minimum or maximum number of properties that may be set on the resulting WebPage object. It may vary from page to page or from time to time, depending on changes to the target URL or systems internal to BrandVantage itself. Web pages with higher amounts of meta-markup will produce better results.

To prevent site abuse, this API will check the corresponding Robots.txt file for the URL given. If access is denied, a Processing Error will return and indicate so in the response body. Requests denied by a Robots.txt rule will be counted against your monthly quota.

Some websites may use anti-extraction techniques such as a CAPTCHA which will affect the ability to access data on these sites. As websites can implement these systems differently, it isn't possible to detect and return a standardised error. This in turn means that requests that are blocked by these techniques are still counted against your monthly quota.

Single Page Applications (SPA) or other pages heavy with JavaScript that affect the markup of the page may have poor results.

Request

curl https://app.brandvantage.co/api/data-source/web-page \
-d apiKey=YOUR_API_KEY \
-d url=TARGET_URL \
-G

private static readonly HttpClient httpClient = new HttpClient();

async Task Main()
{
    var uriBuilder = new UriBuilder("https://app.brandvantage.co/api/data-source/web-page");
    var queryString = new Dictionary<string, string>
    {
        ["apiKey"] = "YOUR_API_KEY",
        ["url"] = "TARGET_URL",
    };
    uriBuilder.Query = string.Join('&', queryString.Select(kvp => $"{kvp.Key}={Uri.EscapeDataString(kvp.Value)}"));

    var json = await httpClient.GetStringAsync(uriBuilder.ToString());
    Console.WriteLine(json);
}

# pip install requests

import requests

endpointUrl = 'https://app.brandvantage.co/api/data-source/web-page'
queryParams = {
    'apiKey': 'YOUR_API_KEY',
    'url': 'TARGET_URL',
}

result = requests.get(endpointUrl, params=queryParams)
print(result.text)

// npm install node-fetch

const fetch = require('node-fetch');
const { URLSearchParams } = require('url');

const endpointUrl = 'https://app.brandvantage.co/api/data-source/web-page';
const params = new URLSearchParams({
    apiKey: 'YOUR_API_KEY',
    url: 'TARGET_URL',
});

(async () => {
    const response = await fetch(endpointUrl + '?' + params);
    console.log(await response.json());
})();

Response

{
  "@type": "WebPage",
  "@context": "https://schema.org",
  "name": "Web Page Name",
  "alternateName": "Website Name",
  "image": {
    "@context": "https://schema.org",
    "@type": "ImageObject",
    "url": "https://example.org/path/to/the-image.jpg"
  },
  "description": "This is an example description for a web page",
  "text": "This is the main content of the page",
  "mainContentOfPage": {
    "@context": "https://schema.org",
    "@type": "WebPageElement",
    "cssSelector": "#main>div>div:nth-child(2)"
  }
}