Feeds¶
A feed is a file that contains a list of ads you want to advertise and is a way to handle repetitive asynchronous bulk uploading of ads.
Once a feed is created you can link your HTTP(s) URL through POST /feed/config or the seller console frontend to make our system fetch your file and import your ads. After that, scheduled fetches happen once per day synchronizing the system with any updates you may want to introduce to the ads list. You can stop the feed advertising process using POST /feed/config/, or the console.
Note
If you have a dedicated account manager, they can also support you by ensuring the URL of your feed is properly connected to your account.
In order to let us download your feed and all the relevant linked content, access to our outgoing IPs should be whitelisted as described in section of the Sellside API.
File Format¶
We support feed files in either an TSV or XML format. Feeds are expected to be in UTF-8 encoding. Information on the most actual set of supported data is described on the details page.
Note
Currently, we have introduced a number of new fields for describing the feed ad. It contains a larger subset of what is considered a ‘widely adopted market standard’. The new fields follow specifications stated in manual for Google Merchant Center customers. For more information see FAQ section.
For instructions on how to create your feed in specific formats, please expand the relevant sections.
TSV
Note
Beware that although double quotes are accepted within a field, a leading quote indicates that the complete field is quoted. In that situation, the parser must look for a terminating quote before the next separator (tab).
"First" second thirdwill not be interpreted as a single field
First "second" thirdis a valid single field
If you need to start a field with quotes then the complete field needs to be enclosed in quotes as well
""First" second third"is a valid single field (notice the complete field is enclosed in quotes)
"\"First\" second third"is a valid single field (you can escape inner quotes, but field also needs to be enclosed in quotes)
TSV format follows specification described on wiki. Column names used in TSV feed must superset column names specified. Some complex fields, like shipping & pick-up or attributes must follow the specified encoding conventions.
XML
The contents of this XML file need to adhere to the XSD available for sellers at GET /feed/xsd. All the values provided should conform to the rules specified for the valid XML document. For the more complex data (that contains, for example HTML tags) we recommend using character data (CDATA). XML escape characters are also supported.
<?xml version="1.0" encoding="UTF-8"?>
<admarkt:ads xmlns:admarkt="http://admarkt.marktplaats.nl/schemas/1.0">
<admarkt:ad>
<admarkt:vendorId>42</admarkt:vendorId>
<admarkt:title>Bally 1992 Adams Family</admarkt:title>
<admarkt:description>Best pinball machine ever made</admarkt:description>
<admarkt:categoryId>999</admarkt:categoryId>
<admarkt:url>https://pinball.com/game/bally-adams-family/</admarkt:url>
<admarkt:vanityUrl>https://pinball.com</admarkt:vanityUrl>
<admarkt:price>870000</admarkt:price>
<admarkt:originalPrice>875000</admarkt:originalPrice>
<admarkt:priceType>FIXED_PRICE</admarkt:priceType>
<admarkt:phoneNumber>16123456789</admarkt:phoneNumber>
<admarkt:emailAdvertiser>true</admarkt:emailAdvertiser>
<admarkt:sellerName>Pinball King</admarkt:sellerName>
<admarkt:status>ACTIVE</admarkt:status>
<admarkt:media>
<admarkt:image url="https://pinball.com/game/bally-adams-family/1.jpg"/>
<admarkt:image url="https://pinball.com/game/bally-adams-family/2.jpg"/>
<admarkt:image url="https://pinball.com/game/bally-adams-family/3.jpg"/>
</admarkt:media>
<admarkt:budget>
<admarkt:cpc/>
<admarkt:autobid>false</admarkt:autobid>
<admarkt:totalBudget>10000</admarkt:totalBudget>
<admarkt:dailyBudget>1000</admarkt:dailyBudget>
</admarkt:budget>
<admarkt:shippingOptions>
<admarkt:shippingOption>
<admarkt:shippingType>PICKUP</admarkt:shippingType>
<admarkt:location>1097DN</admarkt:location>
</admarkt:shippingOption>
<admarkt:shippingOption>
<admarkt:shippingType>SHIP</admarkt:shippingType>
<admarkt:cost>695</admarkt:cost>
<admarkt:time>2d-5d</admarkt:time>
</admarkt:shippingOption>
</admarkt:shippingOptions>
<admarkt:attributes>
<admarkt:attribute>
<admarkt:attributeName>model</admarkt:attributeName>
<admarkt:attributeValue>Adams Family</admarkt:attributeValue>
</admarkt:attribute>
<admarkt:attribute>
<admarkt:attributeName>multiball</admarkt:attributeName>
<admarkt:attributeValue>TRUE</admarkt:attributeValue>
</admarkt:attribute>
<admarkt:attribute>
<admarkt:attributeName>screen size</admarkt:attributeName>
<admarkt:attributeValue>32"</admarkt:attributeValue>
</admarkt:attribute>
<admarkt:attribute>
<admarkt:attributeName>resolutions</admarkt:attributeName>
<admarkt:attributeValue>1024x768:24dpi</admarkt:attributeValue>
<admarkt:attributeValue>800x600:18dpi</admarkt:attributeValue>
</admarkt:attribute>
</admarkt:attributes>
<admarkt:gtin>840639124391</admarkt:gtin>
<admarkt:productType>Hobby & Games > Arcade Games > Pinball Machines</admarkt:productType>
<admarkt:googleProductCategory>Electronics > Arcade Equipment > Pinball Machines</admarkt:googleProductCategory>
<admarkt:brand>Bally</admarkt:brand>
<admarkt:condition>refurbished</admarkt:condition>
<admarkt:energyEfficiencyClass>E</admarkt:energyEfficiencyClass>
<admarkt:minEnergyEfficiencyClass>F</admarkt:minEnergyEfficiencyClass>
<admarkt:maxEnergyEfficiencyClass>D</admarkt:maxEnergyEfficiencyClass>
<admarkt:color>black/white/green</admarkt:color>
<admarkt:gender>unisex</admarkt:gender>
<admarkt:ageGroup>adult</admarkt:ageGroup>
<admarkt:itemGroupId>BC23456</admarkt:itemGroupId>
</admarkt:ad>
</admarkt:ads>
Errors¶
GET /feed/import shows the overview of imported feeds of the user, and GET /feed/import/{id}/detail can be a good source of information on possible errors or warnings on ads, such as missing mandatory attributes or too low CPC etc.
Frequently Asked Questions¶
Below are some common scenarios and questions with their explanations/answers.
How to use TSV format?
We introduced the TSV format in our system, to simplify the integration path. Our customers commonly use spreadsheets to store and manipulate the data, and “TSV export” is a standard option for the majority of spreadsheet programs.
The three important things to remember for successful integration:
There are some column names, that we will look for, and expect to find in your TSV feed.
Multiline fields need to be escaped with double quotes, or all the line breaks changed to \n.
Some complex fields, like shipping & pick-up or attributes must follow the specified encoding conventions.
What are the newly added fields?
Those fields are considered a ‘widely adopted market standard’, required, or recommended for advertising on many other channels: MPN, google product category, product type, brand, GTIN, item group id, condition, material, energy efficiency class, min energy efficiency class, max energy efficiency class, color, gender, age group, size, unit pricing base measure, unit pricing measure.
What happens if my feed file cannot be fetched?
When a feed file cannot be fetched, nothing will change on the user’s ads. It’s as if the import didn’t happen. Since the file represents the desired list of ads to be live, we won’t do anything if we can’t get the file - we cannot read a change in the desired situation.
What happens when my feed file is empty?
When a feed file is empty, all ads of the user will be paused. An empty file means the desired list of ads to be live is empty, so all active ads are paused. Note that this also means that all ads which are in statuses BUDGET_REACHED or DAILY_BUDGET_REACHED are also paused. If you want to pause your entire ad inventory, you can download and use the file below.
My feed file contains only new ads. What happens to those I have previously created via frontend / API?
In the spirit of the feed file being the desired set of ads to be live for a user, all currently active ads (including ads in BUDGET_REACHED or DAILY_BUDGET_REACHED) will be paused and the supplied ads will be created (with status ACTIVE).
Can I modify my feed ads via frontend / API?
The feed file is considered “the desired set of ads to be live for a user”. With every daily import, all the ads will be (re)set to their representing feed values. This means you can see changes made through API or web interface undone after a successful feed import.
I have updated my feed images, and after the successful import there is no change.
If you’re changing the images without changing the URLs, the changes may not be picked up, in case the rest of the ad is also unchanged. We suggest adding a bogus parameter to the image URL to force a re-processing of the ad and its images. Make sure to not change this for every feed import, but only when you require images to be re-processed.
What happens when my XML does not validate against XSD?
If the fetched XML file does not validate against the XSD there will be no changes to your ads. Existing ads will remain unchanged and no new ads will be created.
How to validate XML against XSD?
Next to various online capabilities where you can provide both your XML and XSD files, a way to check quickly and locally is to use a tool called xmllint. With this tool you can use our XSD downloaded from GET /feed/xsd to test whether your feed is working before you let our system fetch it using the following command:
xmllint --debug --noout --schema /path/to/admarkt1.0.xsd /path/to/yourfeed.xml
For small chunks of XML you can use online validators as well, such as http://www.utilities-online.info/xsdvalidation/ or https://www.freeformatter.com/xml-validator-xsd.html. Note that these have a limit on the size of the XML you can check, but it should be more than enough to be able to test the correctness of your structure.