|Table of Contents|
Since a couple of weeks, Spreadshirt API v1 allows you to search for designs on our design marketplace. In this article, I am going to tell you
Our search interface for searching on our design marketplace is quite simple. As explained in Speadshirt API v1 Explained, we provide in general a REST interface that gives you access to most of the data you need for creating custom shops, masss-customization applications or widgets in context of customized apparel, like designs, product types or print types.
Looking at designs in special, you can retrieve marketplace design listings without using the search by using either the URL http https://api.spreadshirt.net/api/v1/shops/205909/designs or http https://api.spreadshirt.com/api/v1/shops/93439/designs depending on whether you want to access the designs on the eu or na platform (eu is shop 205909 and na 93439).
Searching for designs is as easy as retrieving design listings: You simply add the query parameter query to the URL and add your search terms as values, e.g. http https://api.spreadshirt.net/api/v1/shops/205909/designs?query=herz mit pfeil (herz mit pfeil is german and means “heart with arrow”).
Besides stating in the query parameter what you are looking for, you can also provide query parameters for sorting the result, for searching on the marketplace in a specific language, for returning search facets, for conducting a spellcheck in case of typos in the search query or for paging through the search result. A sample query using all possible parameters and thus the full search interface would look like that:
The meaning of the query parameters is as follows:
- Vector – Display results for vector designs only. Valid values are true or false.
An example query would be http https://api.spreadshirt.net/api/v1/shops/205909/designs?query=herz%20mit%20pfeil%20+vector:%28true%29.
- Price – Display results for fixed price or price range. Valid values are all prices, such as 1,59.
An example queries would be http https://api.spreadshirt.net/api/v1/shops/205909/designs?query=herz%20mit%20pfeil%20+price:%280.00%29 or http://api.spreadshirt.net/api/v1/shops/205909/designs?query=herz%20mit%20pfeil%20+price:%5B*%20TO%203.00%5D.
- Date Created – Display results for designs created between two dates. Valid values are all XML date values, such as 2010-08-16 10:01.
An example query is http https://api.spreadshirt.net/api/v1/shops/205909/designs?query=herz%20mit%20pfeil%20+created:%5B*%20TO%202010-09-01%5D.
- User Ids – Display results for specific user only. Valid values are all Spreadshirt user ids, such as as 1 or 40000.
An example query would be http https://api.spreadshirt.net/api/v1/shops/205909/designs?query=herz%20mit%20pfeil%20+userIds:%282068606%29.
- Category Ids – Display results for specific design category only. Valid values are 1000187, 1000188 or 1000189.
An example query would be http https://api.spreadshirt.net/api/v1/shops/205909/designs?query=herz%20mit%20pfeil%20+categoryIds:%281000187%29.
The possible values for the userIds and categoryIds field can be retrieved from the returned facet data (see search result payload below).
Understanding the search interface, we now want to have a look at the returned search result. An example of such a search result is displayed below:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <designs xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net" query="herz mit pfeil" sortOrder="default" sortField="default" count="2209" limit="50" offset="0" xlink:href="httphttps://api.spreadshirt.net/api/v1/shops/205909/designs"> <facets> ... </facets> <design xlink:href="httphttps://api.spreadshirt.net/api/v1/shops/205909/designs/m7195616-1" id="m7195616-1"> <name>Herzen und Sterne</name> <price> <vatExcluded>2.52</vatExcluded> <vatIncluded>3.00</vatIncluded> <vat>19.00</vat> <currency xlink:href="httphttps://api.spreadshirt.net/api/v1/currencies/1" id="1"/> </price> <resources> <resource xlink:href="httphttps://image.spreadshirtspreadshirtmedia.net/image-server/v1/designs/7195616" type="preview" mediaType="png"/> </resources> </design> ...