Zemanta API

Technical Overview ¶

Entities ¶

The diagram and the table below describe the objects this API deals with and the relationships between them.

HTTP Requests ¶

As per the REST convention, the type of action performed is determined by the HTTP method of the request.

Requests that include a JSON formatted body must include the following header in the request:

Content-type: application/json

HTTP Response Status Codes ¶

JSON Payload Format ¶

Entities are represented by JSON objects. Multiple entities are represented as a JSON array of objects.

Request ¶

For POST or PUT requests, the payload is a JSON object or a JSON array of objects, as applicable to the endpoint:

{
    "id": "123",
    "name": "My Campaign"
}

or in the case of a list of entities:

[
    {
        "id": "123",
        "name": "My Campaign"
    },
    {
        "id": "124",
        "name": "My Campaign 2"
    }
]

Response ¶

The server will return an entity or a list of entities in the response payload’s data field:

{
    "data": {
        "id": "123",
        "name": "My Campaign"
    }
}

or in the case of a list of entities:

{
    "data": [
        {
            "id": "123",
            "name": "My Campaign"
        },
        {
            "id": "124",
            "name": "My Campaign 2"
        }
    ]
}

Partial Updates ¶

The API supports partial updates, which means that for all PUT actions, if you’re updating a hypothetical entity

{
    "name": "MyEntity",
    "value": "123"
}

you can send only updated fields as the payload:

{
    "value": "789"
}

which will result in the following entity:

{
    "name": "MyEntity",
    "value": "789"
}

Errors ¶

In case of an error, the server will return a response with the appropriate status code and the payload describing the error:

{
    "errorCode": "ValidationError",
    "details": "Name is required"
}

Pagination ¶

Zemanta One API paginates list views using marker offset pagination by default.

By specifying the offset URL query parameter it is possible to use a simple limit offset pagination which might lead to slow responses with large lists.

Marker Offset Pagination ¶

The format for marker offset pagination URL is:

/rest/v1/{resourceListPath}/{?marker,limit}

Navigation through pages is done by two URL parameters:

• marker: the primary key of the last element in the previous page (the first page has marker=0)

• limit: maximum number of entries to return, up to 1000, defaults to 100

The response has the following content:

{
    "count": 1000,
    "next": "https://oneapi.zemanta.com/rest/v1/{resourceListPath}/?marker=200&limit=100",
    "data": []
}

Limit Offset Pagination ¶

The format for limit offset pagination URL is:

/rest/v1/{resourceListPath}/?offset{,limit}

Navigation through pages is done by two URL parameters:

• offset: the offset of starting element of the page in the list

• limit: maximum number of entries to return, up to 1000, defaults to 100

The response has the following content:

{
    "count": 1000,
    "next": "https://oneapi.zemanta.com/rest/v1/{resourceListPath}/?offset=200&limit=100",
    "previous": "https://oneapi.zemanta.com/rest/v1/{resourceListPath}/?offset=100&limit=100",
    "data": []
}

Rate Limiting ¶

Each Zemanta One user can perform a maximum of 20 requests per second to the Zemanta One API. In case that limit is crossed, the API will start responding with HTTP status 429 (Too Many Requests).

Authentication ¶

Zemanta REST API uses two-legged OAuth2 authentication using client credentials. The client credentials are used to acquire an access token, which must then be passed to all REST API calls as the header

Authorization: Bearer <access_token>

Access tokens are valid for 10 hours, after which a new access token must be obtained using the client credentials. Please cache and reuse access tokens for the duration of their validity.

Create client credentials ¶

To create client credentials, first make sure you are logged in to Zemanta One. Then go to https://one.zemanta.com/o/applications/ and click the New Application button. Enter a name for your application, as shown in the image, and click the “Save” button.

After you click the “Save” button, you will see the details of your newly created application credentials. The provided Client ID and Client Secret are used for API authentication.

Account Management ¶

Campaign Management ¶

Ad Group Management ¶

Content Ad management ¶

Publishers management ¶

Reporting ¶

Getting a report is performed asynchronously. First, you create a report job, then you poll its status and finally, when its status is DONE, you receive a link to a CSV file in the result field.

Filters ¶

Time Filter ¶

{
  "field": "Date",
  "operator": "between",
  "from": "2016-10-01",
  "to": "2016-10-31"
}

Equal Filter ¶

Supported fields: Account Id, Campaign Id, Ad Group Id, Media Source Id

{
  "field": "Ad Group Id",
  "operator": "=",
  "value": "2040"
}

In Filter ¶

Supported fields: Account Id, Campaign Id, Ad Group Id, Content Ad Id, Media Source Id

{
  "field": "Ad Group Id",
  "operator": "IN",
  "values": ["2040", "2041"]
}

Fields ¶

Breakdown Fields ¶

When breakdown fields are specified, the report will be broken down by that field.

Entity breakdown:

• Account, Account Id

• Campaign, Campaign Id

• Ad Group, Ad Group Id

• Content Ad, Content Ad Id

• Media Source, Media Source Id

• Publisher

Time breakdown:

• Day (e.g. 2017-03-30)

• Week (e.g. Week 2017-03-27 - 2017-04-02)

• Month (e.g. Month 3/2017)

Entity Specific Fields ¶

• Account:

  • Total Fee
  • Recognized Flat Fee

• Content Ad:

  • URL
  • Display URL
  • Brand Name
  • Description
  • Image Hash
  • Image URL
  • Call to action
  • Label
  • Uploaded
  • Batch Name

• Media Source:

  • Media Source Slug

Common Fields ¶

• Impressions

• Clicks

• CTR

• Avg. CPC

• Avg. CPM

• Yesterday Spend

• Media Spend

• Data Cost

• License Fee

• Total Spend

• Margin

• Total Spend + Margin

• Visits

• Unique Users

• New Users

• Returning Users

• % New Users

• Pageviews

• Pageviews per Visit

• Bounced Visits

• Non-Bounced Visits

• Bounce Rate

• Total Seconds

• Time on Site

• Avg. Cost per Visit

• Avg. Cost per New Visitor

• Avg. Cost per Pageview

• Avg. Cost per Non-Bounced Visit

• Avg. Cost per Minute

Conversion Fields ¶

To get conversion data in the report, simply specify the same column names as you see them in the Zemanta Dashboard.

For example, if your conversion goal name is “MyGoal”, the valid column names would be

• MyGoal 1 day

• MyGoal 7 days

• MyGoal 30 days

• MyGoal 90 days

Utilities ¶