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
- how our search interface for searching for marketplace designs looks like,
- how our search syntax works and
- how our search result payload looks like.
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://api.spreadshirt.net/api/v1/shops/205909/designs or http://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://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:
- Query – Using the above described URL you can search on the marketplace designs by providing a search query. You provide the search query in a query parameter, e.g. ?query=herz mit pfeil.
- Sorting – You can sort the returned designs in ascending (asc) and descending (desc) order for design attributes score, weight, price and created using sortField and sortOrder parameters, e.g. ?query=herz mit pfeil&sortField=price&sortOrder=desc.
- Locale – As we have different marketplaces on eu an na platform for different languages right now, you can define on which language-specific marketplace you want to search by using the locale parameter, e.g. ?query=herz mit pfeil&locale=de_DE.
- Full Data – In general, the returned XML data only contains lists with partial data, i.e. name, price, image URL, and references to the actual designs. You can either use the given references to fetch the full data of the actual design with a second HTTP call or you can provide the fullData parameter to retrieve a list with the full design data, e.g. ?query=…&fullData=true.
- Paging – As with all lists provided via the API, you can page through through the result using limit and offset parameters, e.g. ?query=…&fullData=…&offset=50&limit=50.
- Facets – You can tell the search that it should provide facet information for the supported facets using the parameter showFacets, e.g. ?query=herz mit pfeil&showFacets=true.
- Spellcheck -You can tell the search that it should provide a suggestedQuery using the parameter spellcheck, in case no results can be found for the given search term. Example is ?query=hrz&spellcheck=true.
Knowing how the search interface looks like in general, we can now go into the details of our search syntax.
- Terms - Terms describe what you are looking for and are separated by spaces, e.g. ?query=herz mit pfeil. Terms are in general AND connected. In case you enter two terms, results that contain both terms will be returned. In case you enter more than two terms, one terms is treated as optional right now.
- Exclusions – You can exclude specific search terms in your search query, and tell the search that you are not interested in designs that contain these terms by using a - (not) in front of the term, e.g. ?query=herz -sterne.
- Phrase Search – You can conduct phrase searches by putting a set of terms in double quotes, e.g. ?query=”gebrochenes herz”.
- Fields – You can search on specific fields by adding the desired field parameter to the search query and defining in a set or range what you want, e.g. ?query=herz +categoryIds:(1000187 1000188 1000189) or ?query=herz +price:[* TO 3.00].
Sets can contain one or more terms. Ranges contain either two valid terms, e.g. [1.00 TO 3.00] or a * as first or second term indicating an open start or end of the range.
The design search supports a fixed set of fields that can be used to further narrow down what you or your customer is looking for. The supported fields and their meaning are as follows:
- Vector – Display results for vector designs only. Valid values are true or false.
An example query would be http://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://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://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://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://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).
Search Result Payload
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:
A search result is in general a list and returned as XML payload. The list consists of one list tag and zero or more entry tags. The list and entry tag names usually correspond to the query URLs last segment name, e.g. designs.
Each search result list tag has a set of canonical attributes. These attributes are as follows:
- Query – The query attribute contains the actual request query, e.g. herz mit pfeil.
- SuggestedQuery – In case you turned the spellcheck on providing the spellcheck=true URL parameter, the suggestedQuery attribute will contain the query the search suggests as correction of your typo, e.g. for a query for hrz this will be herz.
- SortField – The sortField attribute contains either the value default (which means score) in case you did not provide a sortField parameter in your URL, or the given sortField parameter.
- SortOrder - The sortOrder attribute contains either the value default (which means desc) in case you did not provide a sortOrder parameter in your URL, or the given sortOrder parameter.
- Count – The count attribute contains the number of results found for your query, e.g. 2209.
- Offset – The offset attribute contains the value from which the search will start to return results for your query, e.g. 0 or 50. This value is either given as query parameter or is 0 by default.
- Limit – The limit attribute contains the number of entries returned from the offset point, e.g. 10 or 50. This value is either given as query parameter of 50 by default.
In case you turned facets on providing a showFacets=true parameter in your request query, the search result will contain the facet data in the facets tag. Facet data will always contain the id of the facet and the entries found for that facet.
In this blog post, I told you about our search interface, search syntax and search result payload. With this knowledge, you are able to integrate Spreadshirt’s design marketplace search into your custom shops, mass-customization applications or widgets.
Why would you do that? Because even with selling products with designs from other designers to your customers you can earn money!