GET /ad

GET /ad v5 | GET /ad v4 | GET /ad v3

Warning

GET /ad v4 is now officially deprecated and scheduled for removal on May, 1st 2023. Please move to use GET /ad v5.

GET /ad v3 is now officially deprecated and scheduled for removal on July 15th 2020. Please move to use GET /ad v5.

This URL returns a list of ads for the current user and the total size of the result set matching the filter criteria.

GET /ad v5

Scope	api_ro or console_ro
Accept	application/sellside.ad.list-v5+json, application/json

GET /ad v5 is quite similar to GET /ad v3 and GET /ad v4, except for some changes in the Advertisements and an addition of a nextPageToken field in the response struct. The value of this nextPageToken should be used as additional parameter pageToken to your regular call and replaces the usage of the ‘offset’ parameter. This approach allows the caller to paginate through a large list of ads much more efficiently. In essence, it contains encoded information on where the returned result ended, so it can serve as additional filters in the call for the next result set, making that call more efficient. For the very first page, a pageToken should not be provided. For any following page, callers should use the exact same request with an added pageToken parameter. The value for the pageToken parameter for page N+1 is the nextPageToken field in the response of your call to fetch page N. When a response does not contain a nextPageToken you have reached the last page of results and there are no more to fetch.

Note the difference in naming between response field nextpageToken and request parameter pageToken.

GET /ad v5 will return the ads in the response in version V5, similar to GET /ad/{id} v5. See Fields for the documentation on the fields.

Parameters

Name	Type	Description
limit	int	Limits the number of records returned. Default and maximum is 100.
pageToken	string	Encoded information on where the previous page ended, send this along with the same request to get the next page of results. Scales better than offset.
adIds	list of ints	List of ad IDs.
titleKeywords	string	Case-insensitive filter for a keyword in the title.
status	string	Filters the result set by the ad status. Should be a comma separated list of [ACTIVE, PAUSED, DELETED, DELETED_BY_CS, SUSPENDED_BY_CS, BUDGET_REACHED, DAILY_BUDGET_REACHED,DOMAIN_PENDING]. Default value is ACTIVE.
orderBy	string	Orders the result set by the given field. Default value is DATE_CREATED. See Order By.
direction	string	Determines the direction of the sort. Should be one of [ASCENDING, DESCENDING]. Default is ASCENDING.
changedSince	date	Returns ads which have changedSince >= dateLastUpdated.
remainingBudget	string	Returns ads whose remaining budget is below a certain value (absolute number or a percentage).
startDate	string	Determines the startDate of the period to select ads with activity for.
endDate	string	Determines the endDate of the period to select ads with activity for.
categoryIds	list of ints	List of category id’s to filter by. Only leaf category id’s are useful, since ads can only be placed in leaf categories.
campaignId	int	Campaign ID to filter ads by. Only ads being in this campaign are returned.
_include	string	Comma-separated-list of fields to include. Optional, default is all fields.
_exclude	string	Comma-separated-list of fields to omit. Optional, default empty.

Example

GET /ad[?limit=limit][&pageToken=eyJpZCI6MTAwMT....][&orderBy=orderBy][&titleKeywords=titleKeywords][&status=Status][&changedSince=timestamp][&remainingBudget=number[%]][&_include=list,of,fields][&_exclude=list,of,fields][&adIds=123,456,457][&campaignId=6531][&startDate=2014-12-04][&endDate=2015-06-13]
Accept: application/sellside.ad.list-v5+json, application/json

200 OK
Content-Type: application/sellside.ad.list-v5+json; charset=utf-8

{
  "ads": [
    {
      "id": 42,
      "title": "Brother Fax voor 99,99",
      "description": "<b>NU extra voordelig op ourshop.com.</b> Fax nu voor slechts <b>99,99!</b>",
      "categoryId": 826,
      "status": "ACTIVE",
      "price": {
        "priceType": "FIXED_PRICE",
        "priceUnit": "per_sqm",
        "amountCents": 5600,
        "originalAmountCents": 6500
      },
      "bidMicros": "10000",
      "budgets": {
        "daily": {
          "limitMicros": "UNLIMITED",
          "spentMicros": "1255000"
        },
        "total": {
          "limitMicros": "350000000",
          "spentMicros": "24370000"
        }
      },
      "salutation": "COMPANY",
      "sellerName": "My Shop",
      "postcode": "1097DN",
      "regionId": 1700195,
      "phoneNumber": "0207894561",
      "allowContactByEmail": true,
      "dateCreated": "2012-08-31T16:12:53Z",
      "dateLastUpdated": "2012-09-05T04:03:42Z",
      "vendorId": "OURSHOP-1423453-34",
      "campaignId": 124152,
      "links": {
        "self": "/ad/42",
        "category": "/category/826",
        "displayUrl": "www.ourshop.com/Faxes",
        "url": "http://www.ourshop.com/index.php?param1=value1&amp;param2=value2&amp;param3=value3"
      },
      "images": [
        {
          "src": "http://www.ourshop.com/img/brother_fax_big.jpg",
          "status": "OK",
          "dateLastUpdated": "2012-09-10T13:11:05Z",
          "links": {
            "50x70": "//i.marktplaats.nl/image23434_abc.jpg",
            "120x180": "//i.marktplaats.nl/image23434_def.jpg"
          }
        },
        {
          "src": "http://www.ourshop.com/img/brother_fax_side.jpg",
          "status": "OK",
          "dateLastUpdated": "2012-09-10T13:11:05Z",
          "links": {
            "50x70": "//i.marktplaats.nl/image397493_abc.jpg",
            "120x180": "//i.marktplaats.nl/image397493_def.jpg"
          }
        }
      ],
      "attributes": [
        {
          "key": "color",
          "label": "Kleur",
          "locale": "nl",
          "type": "STRING",
          "value": "Zwart",
          "recognized": true
        },
        {
          "key": "size",
          "label": "Maat",
          "locale": "nl",
          "type": "NUMBER",
          "value": 6,
          "recognized": true
        },
        {
          "key": "software",
          "label": "Software",
          "locale": "nl",
          "type": "LIST",
          "value": [
            "Apple OSX",
            "Microsoft Windows 7"
          ],
          "recognized": false
        }
      ],
      "shippingOptions": [
        {
          "type": "SHIP",
          "costCents": 495,
          "time": "2d-5d"
        },
        {
          "type": "PICKUP",
          "pickupLocation": "1097DN"
        }
      ]
    }
  ],
  "count": 4,
  "nextPageToken": "eyJpZCI6MTAwMTgzMTc1MCwic3RyaW5nX3ZhbHVlIjpudWxsLCJpbnQ2NF92YWx1ZSI6MTM0MDIxNzg1OTc5MH0"
}

GET /ad v4

Scope	api_ro or console_ro
Accept	application/sellside.ad.list-v4+json, application/json

Note

The only backwards-incompatible change from GET /ad v3 is with respect to the usage of startDate and endDate parameters. Namely, ads which were live during this selected period but did not receive a single click, impression, urlClick, etc (any visitors activity) will be filtered out. This does not include ads which received updates anymore.

In addition, the response contains a field statusReasons. This field is currently used to indicate the reason why a certain ad might be set to a certain status by our system. This could be due to, for example, an action (like new website domain approval) pending from the user, which is a mechanism used to prevent account takeovers from setting the website URL to a malicious one.

Example

GET /ad[?limit=limit][&offset=offset][&titleKeywords=titleKeywords][&status=Status][&orderBy=orderBy][&changedSince=timestamp][&remainingBudget=number[%]][&_include=list,of,fields][&_exclude=list,of,fields][&startDate=2014-12-04][&endDate=2015-06-13]
Accept: application/sellside.ad.list-v4+json, application/json

200 OK
Content-Type: application/sellside.ad.list-v4+json; charset=utf-8

{
  "ads": [
    {
      "links": {
        "category": "/api/sellside/category/453",
        "self": "/api/sellside/ad/3000000604"
      },
      "id": 3000000604,
      "title": "Franks fiets",
      "description": "mijn fiets",
      "categoryId": 453,
      "externalId": "79fb0210-f53c-4663-83c4-6f9de776e98b",
      "currency": "EUR",
      "priceType": "FIXED_PRICE",
      "price": 12300,
      "cpc": 7,
      "totalBudget": 10000,
      "spentBudget": 0,
      "salutation": "COMPANY",
      "sellerName": "Test schildersbedrijf",
      "phoneNumber": "0612345678",
      "allowContactByEmail": true,
      "allowPaypal": false,
      "status": "ACTIVE",
      "postcode": "1011DK",
      "pageNumber": 1,
      "suggestedCpcForPageOne": 5,
      "dateCreated": "2015-06-15T15:06:08Z",
      "dateLastUpdated": "2015-06-15T15:06:08Z",
      "vendorId": "OURSHOP-1423453-34",
      "microTip": "30% korting",
      "attributes": [
        {
          "key": "condition",
          "label": "Conditie",
          "locale": "nl",
          "type": "STRING",
          "value": "Nieuw",
          "recognized": true
        },
        {
          "key": "brand",
          "label": "Merk",
          "locale": "nl",
          "type": "STRING",
          "value": "Gazelle",
          "recognized": true
        },
        {
          "key": "frameHeight",
          "label": "Framehoogte",
          "locale": "nl",
          "type": "STRING",
          "value": "57 tot 61 cm",
          "recognized": true
        },
        {
          "key": "properties",
          "label": "Eigenschappen",
          "locale": "nl",
          "type": "LIST",
          "value": [
            "Versnellingen"
          ],
          "recognized": true
        }
      ],
      "images": [],
      "shippingOptions": [],
      "statusReasons": []
    }
  ],
  "count": 1
}

GET /ad v3

Warning

GET /ad v3 is now officially deprecated and scheduled for removal on July 15th 2020. Please move to use GET /ad v4. If you were not using startDate or endDate parameters in your calls the output will be the same in GET /ad v4.

Scope	api_ro or console_ro
Accept	application/sellside.ad.list-v3+json, application/json

The number of ads returned can be limited with the limit parameter. The offset parameter allows to skip some ads and together with limit allows for pagination.

The status parameter returns only ads with the given status. The default is to return only ads with status ACTIVE.

The orderBy and direction parameters control the sort field and direction.

The titleKeywords parameter is case-insensitive and will include only ads which contain the given keyword in their title.

The changedSince parameter can be used to retrieve only ads that have dateLastUpdated >= changedSince. The changedSince value must be a valid ISO 8601 UTC date which usually lies in the past but cannot lie in the future.

The changedSince parameter should only be combined with limit and offset. Filtering by status and titleKeyword may be used but orderBy and direction cannot be changed since this would break the pagination.

The remainingBudget parameter can be used to retrieve only ads whose remaining budget (totalBudget - spentBudget) is below a given threshold. The remainingBudget value must be an absolute integer number (e.g. 123) or a percentage (e.g. 10%).

The startDate and endDate parameters can be used to define a period. The values for both should be valid dates represented as ‘yyyy-MM-dd’, and the endDate should represent a date equal or after the startDate. The ads returned have had activity in this period. Note that ads which were live during this period but did not recieve a single click, impression or urlClick, and did not have any updates in this period, will be filtered out.

Note

The fields pageNumber and suggestedCpcForPageOne are currently expensive to compute. If you do not need their values consider excluding them to speed up the response. To exclude the fields add the following parameter to the request URL.

?_exclude=pageNumber,suggestedCpcForPageOne

Caching all ads for a user

If an application needs to keep a cache of the entire set of ads for a user then it should perform the following steps:

1. Fetch all ads by using limit and offset for older versions, or using pageToken for newer versions until all ads have been retrieved. No filters should be used.

2. Retrieve updates by using changedSince, limit and offset. No additional filters should be used. changedSince should be set to a value a somewhat before (e.g. 1 min) of dateLastUpdated of the last modified ad.

Due to the nature of this system retrieving updates as described in step 2 will always return at least the ad that was modified last. Also, the API can currently not guarantee that all updates are retrieved when changedSince is set to dateLastUpdated of the last modified ad. That’s why you should use dateLastUpdated - 1 minute. To determine whether an ad has changed compare the dateLastUpdated value.

Unless you have a very small set of ads (< 10) do not retrieve all ads every time since this will not give you decent performance and also puts unnecessary load on the system.

Parameters

Name	Type	Description
limit	int	Limits the number of records returned. Default and maximum is 100.
offset	int	Skips the first N records.
titleKeywords	string	Case-insensitive filter for a keyword in the title.
status	string	Filters the result set by the ad status. Should be a comma separated list of [ACTIVE, PAUSED, DELETED, DELETED_BY_CS, SUSPENDED_BY_CS, BUDGET_REACHED, DAILY_BUDGET_REACHED]. Default value is ACTIVE.
orderBy	string	Orders the result set by the given field. Default value is DATE_CREATED. See Order By.
direction	string	Determines the direction of the sort. Should be one of [ASCENDING, DESCENDING]. Default is ASCENDING.
changedSince	date	Returns ads which have changedSince >= dateLastUpdated.
remainingBudget	string	Returns ads whose remaining budget is below a certain value (absolute number or a percentage).
startDate	string	Determines the startDate of the period to select ads with activity for.
endDate	string	Determines the endDate of the period to select ads with activity for.
externalId	string	Only ads matching this externalId will be returned. Optional.
categoryIds	list of ints	List of category id’s to filter by. Only leaf category id’s are useful, since ads can only be placed in leaf categories.
_include	string	Comma-separated-list of fields to include. Optional, default is all fields.
_exclude	string	Comma-separated-list of fields to omit. Optional, default empty.

Order By

Value	Description
DATE_CREATED	Default. Will order ads by creation date.
DATE_LAST_UPDATED	Will order ads by last modification date.
STATUS	Will order ads by Status; This is an internally defined ordering intended to have ads requiring attention on top/bottom, depending on direction.
CLICKS	Will order ads by lifetime number of clicks received.
TITLE	Will order ads alphabetically by title
CPC	Will order ads by current CPC
SPENT	Will order ads by lifetime spent amount
REMAINING_BUDGET	Will order ads by current remaining budget
AD_ID	Will order ads by their ID

Errors

Field	Code	Error message	Description
limit	2001	invalid argument	not a valid number
limit	2002	out of range	less than 1 or greater than 100.
offset	2001	invalid argument	not a valid number
offset	2002	out of range	less than 0.
titleKeywords	2004	value too short	must be 3 characters or more.
status	2001	invalid argument	not a recognised status to filter on
orderBy	2001	invalid argument	not a recognised orderBy to filter on
direction	2001	invalid argument	not a recognised direction to filter on
changedSince	2001	invalid argument	not a valid date
changedSince	2002	out of range	date is in the future
remainingBudget	2001	invalid argument	remaining budget is not an integer or an integer percentage (e.g. 10%)
startDate	2001	invalid argument	startDate should be a valid date in form ‘yyyy-MM-dd’
endDate	2001	invalid argument	endDate should be a valid date in form ‘yyyy-MM-dd’
startDate/endDate	2002	out of range	endDate should be equal or after startDate

Example

GET /ad[?limit=limit][&offset=offset][&titleKeywords=titleKeywords][&status=Status][&orderBy=orderBy][&changedSince=timestamp][&remainingBudget=number[%]][&_include=list,of,fields][&_exclude=list,of,fields][&startDate=2014-12-04][&endDate=2015-06-13]
Accept: application/sellside.ad.list-v3+json, application/json

200 OK
Content-Type: application/sellside.ad.list-v3+json; charset=utf-8

{
  "ads": [
    {
      "links": {
        "category": "/api/sellside/category/453",
        "self": "/api/sellside/ad/3000000604"
      },
      "id": 3000000604,
      "title": "Franks fiets",
      "description": "mijn fiets",
      "categoryId": 453,
      "externalId": "79fb0210-f53c-4663-83c4-6f9de776e98b",
      "currency": "EUR",
      "priceType": "FIXED_PRICE",
      "price": 12300,
      "cpc": 7,
      "totalBudget": 10000,
      "spentBudget": 0,
      "salutation": "COMPANY",
      "sellerName": "Test schildersbedrijf",
      "phoneNumber": "0612345678",
      "allowContactByEmail": true,
      "allowPaypal": false,
      "status": "ACTIVE",
      "postcode": "1011DK",
      "pageNumber": 1,
      "suggestedCpcForPageOne": 5,
      "dateCreated": "2015-06-15T15:06:08Z",
      "dateLastUpdated": "2015-06-15T15:06:08Z",
      "vendorId": "OURSHOP-1423453-34",
      "microTip": "high quality",
      "attributes": [
        {
          "key": "condition",
          "label": "Conditie",
          "locale": "nl",
          "type": "STRING",
          "value": "Nieuw",
          "recognized": true
        },
        {
          "key": "brand",
          "label": "Merk",
          "locale": "nl",
          "type": "STRING",
          "value": "Gazelle",
          "recognized": true
        },
        {
          "key": "frameHeight",
          "label": "Framehoogte",
          "locale": "nl",
          "type": "STRING",
          "value": "57 tot 61 cm",
          "recognized": true
        },
        {
          "key": "properties",
          "label": "Eigenschappen",
          "locale": "nl",
          "type": "LIST",
          "value": [
            "Versnellingen"
          ],
          "recognized": true
        }
      ],
      "images": [],
      "shippingOptions": []
    }
  ],
  "count": 1
}