assets resource endpoint
The bare "assets" endpoint allows a caller to search for assets across the whole of TypePad or search constrained to a particular user, blog or group.
This endpoint supports full-text search queries and a variety of filters. These can be combined together to form arbitrary queries. All requests to this endpoint must include a query string and may include one or more filters.
Full-text search queries are performed using the q query argument. A query is a string of matching tokens separated by spaces.
The most basic form of matching token is a simple keyword, which matches any item which contains that keyword in any of its properties. If a set of keywords are included in quotes, these words must appear together in any of the item's properties.
Matching tokens can be prefixed with title: or content: to match only within the item's title and content respectively.
The symbol - (minus) can be prefixed to any matching token to negate its meaning.
All queries must have at least one positive token. It is not valid to provide an all-negative query string.
Example Full-text Queries
- Return only assets containing the word "cheese" in any property.
- cheese pizza
- Return only assets containing both the word "cheese" and the word "pizza" in any property.
- "cheese pizza"
- Return only assets containing the word "cheese" immediately followed by the word "pizza" in any property.
- Return only assets containing the word "cheese" in the title.
- title:"cheese pizza"
- Return only assets containing the word "cheese" immediately followed by the word "pizza" in the title.
- title:cheese pizza
- Return only assets containing the word "cheese" in the title and the word pizza in any property.
- cheese -pizza
- Return only assets which contain the word "cheese" in any property and which do not contain the word "pizza" in any property.
- cheese -title:pizza
- Return only assets which contain the word "cheese" in any property and which do not contain the word "pizza" in the title.
Filter parameters can be used with a full-text search query in order to constrain the set of assets that will be searched.
The set of supported filter criteria is enumerated in full in the list of query arguments supported by this endpoint below. All of the filter parameters have the prefix filter. and accept a comma-separated list.
The filter.asset-type parameter accepts a list of names of the subtypes of Asset and will constrain the resultset to contain only assets of that type. For example, filter.asset-type=Photo,Video,Link.
The filter.asset-rank parameter will constrain the resultset depending on a high-level heirarchy of assets: the keyword toplevel matches posts and pages in blogs and the various asset types that can be posted at the top level in a group. The keyword subordinate matches comments and trackbacks. The keyword embedded matches media assets that are not directly part of a blog or group but might be embedded in or linked from a top-level asset.
The default value for filter.asset-rank is toplevel. Requests for a rank of embedded are only permitted for authenticated requests in which the filter.owner parameter is set to the urlId property of the requesting user. In other words, it is only permitted for a user to query his or her own embedded assets.
The following keywords are accepted for the sort argument to control the ordering of the returned results:
- Results are first ordered by their age with newest first and then ordered by relevance. This is the default.
- Results are ordered by relevance, disregarding age.
- Results are ordered by publication time with oldest first, disregarding relevance.
- Results are ordered by publication time with newest first, disregarding relevance.
Obtaining More Results
The response to an initial query will contain up to 50 results, depending on max-results query string parameter. To retrieve more results, a client can send a follow-up query with all of the query arguments replaced with the single argument start-token, whose value is exactly the value of the property moreResultsToken in the initial response.
If the response does not include moreResultsToken then there are no more results to retrieve. Clients may continue to submit follow-up requests with new tokens until there are no further results or until the search resultset expires, whichever comes first. Clients must be prepared to accept an empty resultset in response to a follow-up request.
|GET||Search for user-created content across the whole of TypePad.|
Query String Arguments
- The value of the moreResultsToken property of a previous response, to retrieve more items from the same query.
- Maximum number of items to return in the list response.
- Query string for full-text search.
- Keyword specifying how the results are to be sorted.
- A list of user urlIds which will constrain the search to assets owned by these users.
- A list of urlIds for groups to constrain the search to.
- A list of asset ranks which will constrain the search to assets of the given ranks.
- A list of urlIds for blogs to constrain the search to.
- A list of user urlIds which will constrain the search to assets created by these users.
- A list of type keywords which will constrain the search to assets of the given types.
This endpoint returns an object of type Stream<Asset>.
- entries (array<Asset>)
- The items within the selected range.
- estimatedTotalResults (integer)
- An estimate of the total number of items in the whole stream of which this object is a chunk. null if a count cannot be determined at all, or if an exact count is returned in totalResults.
- moreResultsToken (string)
- An opaque token that can be used as the start-token parameter of a followup request to retrieve additional results. null if there are no more results to retrieve, but the presence of this token does not guarantee that the response to a followup request will actually contain results.
- totalResults (integer)
- The total number of items in the whole stream of which this object is a chunk. null if an exact count cannot be determined.
Client Library Methods for PHP
- Search for user-created content across the whole of TypePad.
$tp->assets->search(array( # Optional Parameters "filterByAssetRank" => $filterByAssetRank, "filterByAssetType" => $filterByAssetType, "filterByAuthor" => $filterByAuthor, "filterByBlog" => $filterByBlog, "filterByGroup" => $filterByGroup, "filterByOwner" => $filterByOwner, "limit" => $limit, "q" => $q, "sort" => $sort, "startToken" => $startToken, ))