Roomy.co.za
Roomy Search Services
Welcome to Roomy.co.za our Internal Content Search and Embed API - please use per the details below the details below to access our content
- Version: 0.1
- Author: Around Design
- Created: 12 April, 2022
- Update: 12 April, 2022
If you have any questions that are beyond the scope of this help file, Please feel free to email via Item Support Page.
URL Formation & Structure
Follow the this URL structure to setup your query:
https://roomy.co.za/ project?q=& category=& num=& exclude=& source=& last=& mode=& format=& affiliate=
Searching Filters
Follow the steps below to setup your site template:
project
project is unique for each roomy search service. Each "project" contains a unique set of content that is maintained by the Roomy Content API. Only 1 "project" can be used in a search query.
project has the following caveats:
| Attributes | Value |
|---|---|
Default value | No default value |
| Can Be Omitted? | Cannot be omitted in URL |
| Case Sensitive? | Yes needs to match exactly |
q or query
q is the query of the search, one or more search words, can be joined by a space (be sure to encode to %20), or dash -> , or plus sign +. When more than 1 words in search, it perform as the OR opertator between all words.
q has the following caveats:
| Attributes | Value |
|---|---|
Default value | No default value |
| Minimal length | 3 Characters |
| Maximum length | 50 characters Everything beyond 50 characters will be ignored |
| Can Be Omitted? | Can be omitted - in which case all content will be output (after subsequent filters in URL are applied ) |
| Case Sensitive? | Search words are not case sensitive but English only. Only single form need be included as other forms will automatically be inferred .e.g. If "land" is entered it will return results for "land", "landed", "landing" etc. General fulltext stopwords will be ignored, e.g. "and", "as", "do" etc. |
num or qty
num defines how many elements to output.
num has the following caveats:
| Attributes | Value |
|---|---|
Default value | 100 |
Minimal value | 10 |
Maximum value | 500 |
| Can Be Omitted? | Can be omitted - will then fallback to deflaut value (100) |
| Case Sensitive? | Yes, needs to match exactly |
cat or category
cat defines how many elements to output.
cat has the following caveats:
| Attributes | Value |
|---|---|
Default value | n/a |
| Minimal Categories | 1 |
| Maximum Categories | 10 |
| Can Be Omitted? | Can be omitted - then results won't be filtered by category |
| Case Sensitive? | Yes, needs to match exactly |
source
source of the content. Same format as category
source has the following caveats:
| Attributes | Value |
|---|---|
Default value | n/a |
| Minimal Categories | 1 |
| Maximum Categories | 10 |
| Can Be Omitted? | Can be omitted - then results won't be filtered by source |
| Case Sensitive? | Yes, needs to match exactly |
exclude
Filter results by excluding certain results by domain or url
exclude has the following caveats:
Domain
| Attributes | Value |
|---|---|
| Input a domain name | Results won't come from excluded domain name and all sub-domain names. E.g. example.com will exclude result from example.com and *.example.com |
| Case Sensitive? | No, domain name will be converted to lowercase |
Url
| Attributes | Value |
|---|---|
| Input a URL | Exactly matched URL will be removed from the result. Please note, protocol part won't be used for match. E.g either http:// or https:// and will match both http:// and https:// |
| Can be Omitted? | Can be omitted, then no exclusion will occur |
| Maximum Length | Longest string allowed is 100 characters |
| Case Sensitive? | Yes for URL, need exactly match |
last
last outputs results from a defined time period onward. Any results older than that won't be output.
last has the following caveats:
| Attributes | Value |
|---|---|
Allowed values | define days e.g: 1d, 2d, 3d ... 30ddefine months e.g: 1m, 2m, 3m ... 12mdefine years: e.g: 1y, 2y, 3y ... 12y |
| Default Value | 1y |
| Can Be Omitted? | Can be omitted - will then fallback to default value (1y) |
| Out Of Range? | If out of range - will then fallback to default value (1y) |
| Case Sensitive? | Yes, needs to match exactly |
mode
mode defines how search works and how to get results.
loose or strict has the following caveats:
| Attributes | Value |
|---|---|
loose | use value loose to output search results first, then add search result by ignoring last (means searching from whole content under project), then output most recent entries based on "time", until reach num, or out of content. loose mode will try to output all possible content to match the needed num. |
strict | use value strict, to only output matched results |
| Default Value | loose |
| Can Be Omitted? | Can be omitted - will then fallback to default value (loose) |
format
Output format currently only supports RSS (with Media RSS Namespace Extension) and JSON format.
format has the following caveats:
| Attributes | Value |
|---|---|
| Default value | rss |
| Can Be Omitted? | Can be omitted - will then fallback to default value (rss) |
affiliate
Certain projects support affiliate programs. If applicable, one can define affiliate reference here. When defined, output link will be append #affiliate at the end. e.g. if defaulted affiliate=roomy, then #roomy will be appended to the end of the link of every output result.
affiliate or strict has the following caveats:
| Attributes | Value |
|---|---|
| Default Value | none |
Minimal length | 1 Character |
Maximum length | 50 Characters |
Allowed characters | Letters and numbers. underscores (_), dots (.), and dashs (-). |
Format check | [\w\.\-]{1,50} |
| Can Be Omitted? | Can be omitted - will then fallback to default value (none) |
Changelog
See what's new added, changed, fixed, improved or updated in the latest versions.
Version 0.1 (12 April, 2022)
Initial Release