API - Planyo Web Services - resource_search

You are here: Planyo » Help » API » resource_search

resource_search (version 1)

Description:

Searches for available resources for given time period. The results can be returned as raw data or as HTML code depending on the value of the optional 'output' parameter.

Input:

start_time DateTime required
Desired start time. Can be a timestamp or text.
end_time DateTime required
Desired end time. Can be a timestamp or text. In case of whole-day reservations, enter either the date following the rental date without time or the actual end date with the hour set to 23:59. E.g. for the entire day: 1st of January 2013, enter 2013-01-01 23:59:00 as the end time. In case of night reservations (e.g. accommodations), enter the departure date without any time. E.g. to reserve a single night of the 1st of January 2013, enter 2013-01-02 (=departure date).
site_id int optional
Planyo site ID (needed if using a metasite api key and you only want the results to come from a single site)
site_ids int optional
Comma separated site IDs (needed if using a metasite api key and you want to filter the results so they only come from specific sites)
quantity int required
Desired number of units
sort string optional
Sort criterium. One of: price, resname (resource name), site (site ID), location, prop_res_xyz (sorted by one of the resource-specific properties defined in the admin panel in: Site settings / Custom resource properties). E.g. for a custom property 'distance to sea', this would be prop_res_distance_to_sea (where '_' replaces all space characters)
prop_res_xyz string optional
Resource-specific properties (defined in the admin panel in: Site settings / Custom resource properties). E.g. for a custom property 'distance to sea', this would be prop_res_distance_to_sea (where '_' replaces all space characters). If you want to look for values greater or less than a specific number (e.g. hotels with specific max. distance to sea), prefix the value with one of the following operators: <, >, <=, >= e.g. prop_res_distance_to_sea = <500. On the other hand, the [inlcude] prefix finds values that include the requested text, e.g. 'prop_res_desc = [include]find me'.
prop_cal_xyz string optional
Site level properties to be used as a search filter. Site-level properties can be added when using a metasite.
ppp_resfilter string optional
You can limit IDs of resources being searched by specifying a comma-separated ID list.
output string optional
If set to 'html', the results will be returned in form of HTML code that can be embedded on your web site. By default (when this parameter is skipped) the results will be returned as data.
detail_level int optional
Sum of one or more of the following integers (ORed value): 1=resource name & settings & search result information, 4=resource properties (resource-specific properties), 8=resource photos, 16=site properties (useful when doing a search using a metasite API key). Default value is 5 (=1+4 which returns the basic info and resource properties). Note: This parameter is ignored when output is not set to html (the search template can include all tags).
range_search string optional
Use this parameter to change the search mode to a flexible search. See range_search in Q167 for more information. For example, setting range_search=1 with a long search period (start_time and end_time being different dates) will also find resources available only for short rentals between these times.
list_unavailable_resources bool optional
If you set this to true, the search results will also include unavailable resources. Each such result will then include the field is_unavailable with the value of 1.
admin_mode bool optional
If set to true, the response will be given for the admin, meaning that for example dates which are vacationed will still be reservable and the time-related restrictions will not be checked. This is the same as when the administrator makes a reservation using the UI (the conditions are much less strict as for regular customers). The default value is false. You can also set it to the following special values: vacations - this will return results as for the admins (no restrictions) but vacations will not be reservable, all - this will return results for BOTH the admin and the normal customer -- the normal customer results will be returned in an array with the key results_non_admin (only resource IDs). You can also combine the two values: all,vacations.
ppp_gps_coords_radius string optional
If you want to do a geolocation search (see Q281 for more about this), you must pass the distance from a point using this parameter (use the 'm' suffix to indicate if the distance is in miles, for kilometers use the 'km' suffix or no suffix at all, just a float) and you should set the coordinates of the search point (latitude followed by a comma and then longitude in decimal degrees, e.g. 46.17,8.80) using the parameter prop_res_gps_coords (if the coordinates of the resources should be used) or prop_cal_gps_coords (if the coordinates on the site level should be used -- only for metasite api keys). Only the results within specified distance from the given point will be returned. Additionally the distance in kilometers will be returned for each result ('distance' key).
version float optional
you can optionally specify the version of the API that you're using. Use the value of latest or simply skip this parameter to use the latest API version. The latest version is: 1
language string optional
by specifying a 2-letter (ISO 639-1) language code (all capital letters e.g. EN, DE, FR, ES, IT) you can change the language of the text values returned
api_key string required
your API key - Click here to get your key. If your API key uses a hash key, you must also include the parameters hash_key and hash_timestamp.

Output:

results array
If no output was set, this will be the array of results matching the search criteria. Each array element is a named array with the following fields: id, name, total_price, resource settings (as in list_resources including custom resource properties), photos (array of photos containing following keys: id, path, title) and site info (site_id and site_name).
code string
If the 'output' parameter was set to 'html', this is the output HTML code. The formatting of the results is determined by the template used (Settings / Integrate with your site / Availability search box / Search result templates)
reason_not_listed array
You'll find text messages with information about why the resources which are not found in the search results are not listed here.

API playground:

Click here to test this function in the API playground.