Distributed Peer-to-Peer Web Search Engine and Intranet Search Appliance
page: htroot/yacysearch.html help: help/yacysearch.md title: Search Page package: core-search-public access: mixed kind: search-page backend_java: source/net/yacy/htroot/yacysearch.java
Search Page
Purpose
The Search Page is the main result page. It turns a query into local or distributed search results and carries the parameters that define result count, content type, language, pagination, and verification behavior.
Use it to understand how a browser search maps to an API-style request.
What You Can Do Here
- Search the local YaCy index, or the YaCy network when the peer is configured for global search.
- Choose query, result type, collection, and verification options according to the information need.
- Page through results, restrict results to a URL pattern, request a content type such as images or text, and choose how fresh snippets must be.
- When authenticated, perform result actions such as deleting a reference, recommending a result, bookmarking it, or sending a URL to a blacklist.
Page Architecture
Public search pages turn request parameters into result lists, previews, snippets, feeds, or integration fragments. They are mostly read-oriented, but some result actions can bookmark, recommend, blacklist, or delete references when authenticated.
| Control | Meaning | Values or examples |
|---|---|---|
query |
Search text. Use ordinary search terms, quoted phrases where supported by YaCy query parsing, and optional YaCy modifiers such as collection filters when you intentionally need them. | Search terms, for example climate data or a more specific phrase. |
Enter |
Browser submit button. Omit it from direct API calls; YaCy uses the query and filter parameters, not the button label, to run the search. | Browser-generated submit value only. |
Correct Use
For a normal search, send only query and the options that express the user intent: maximumRecords for result count, resource for local versus network search, contentdom for text or media, and urlmaskfilter when the user asks to search inside a site. Start with verify=iffresh when freshness matters; use cacheonly only when the user explicitly wants stored snippets without refetching.
Do not send result-action parameters such as deleteref, bookmarkref, or blacklisturl as part of an ordinary search. Those parameters change state and require an exact result reference from a prior response.
Access And Safety
The page may be visible, but the backend performs authentication checks for protected actions.
Protected related endpoint(s): /yacysearch.html.
Backend checks: built-in administrator authentication for protected search features and all state-changing result actions.
Automation And API
Page backend: source/net/yacy/htroot/yacysearch.java.
| Endpoint | Method | Access | Backend |
|---|---|---|---|
/yacysearch.html |
GET |
mixed | source/net/yacy/htroot/yacysearch.java |
Parameter Guide
The table explains values that an agent or script must set deliberately. Parameters not relevant to a task should be omitted or left at the page default. Low-level generated parameters are omitted when they are only meaningful inside the rendered YaCy form.
| Parameter | Meaning and valid values | Care |
|---|---|---|
query |
Search text. Use ordinary search terms, quoted phrases where supported by YaCy query parsing, and optional YaCy modifiers such as collection filters when you intentionally need them. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
auth |
Requests authentication-aware behavior when the endpoint supports user-specific or protected actions. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
callback |
JSONP callback name for legacy script clients. Leave empty for normal HTML or JSON-style use. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
collection |
Collection name. Use it to group crawled or imported documents and to search or manage that group later. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
constraint |
Encoded YaCy bitfield constraint. Leave it empty unless you are replaying a URL generated by YaCy itself. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
contentdom |
Content domain filter. Common values are all, text, image, audio, video, and app; use it to ask for web pages, media, or application documents deliberately. |
Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
count |
SRU-style result count. It is an alternative to maximumRecords on search endpoints. |
Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
deleteref |
URL hash/reference selected for deletion from results. Use only with administrator intent and an exact known reference. | Can remove data, stop work, expose access, or make a broad operational change. Use only with explicit confirmation and an exact target. |
focus |
Browser presentation flag controlling whether the search input receives focus. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
indexof |
Interprets the query as an index-of style request when supported. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
lr |
Language filter, usually a two-letter code such as de, fr, or en when the page supports language-restricted search. |
Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
maximumRecords |
Maximum number of results to return on one page. Use a modest value for interactive use; larger values are for controlled scripts. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
nav |
Navigator/facet selection for search results. all requests the normal set; narrower values reduce displayed facets. |
Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
offset |
Zero-based result offset for pagination. | Read-only pagination control. Use 0 for the first page and increase by the result count for later pages. |
prefermaskfilter |
Regular-expression URL preference. Matching results are favored without excluding all others. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
recommendref |
URL hash/reference selected for recommendation. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
resortCachedResults |
Requests resorting of a cached search event instead of starting a fully fresh result event. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
resource |
Search source. local searches this peer index; global may use the YaCy network when the peer and configuration allow it. |
Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
resource-switch |
Browser control for switching between local and global search. For direct calls use resource=local or resource=global. |
Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
rows |
Rows requested by API-style clients. It is another result-count alias on search endpoints. | Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
search |
Alternative search text parameter accepted by some search endpoints; prefer query on browser search pages unless reproducing an existing URL. |
Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
startRecord |
First result record for pagination; accepted as an alternative to offset on search endpoints. |
Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
strictContentDom |
When true, YaCy enforces the selected content domain more strictly instead of using it mainly for presentation. | Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
timezoneOffset |
Client timezone offset in minutes. YaCy uses it for date display or schedule calculations. | Read-only context for date handling; it does not by itself change the index. |
urlmaskfilter |
Regular-expression URL filter for search results. Use .* for no restriction; use a precise host/path expression to search inside a site or section. |
Controls the scope or format of the result. Prefer the narrowest value that answers the request. |
verify |
Snippet/cache verification strategy. Typical values are iffresh, ifexist, cacheonly, nocache, and false; choose according to whether freshness or speed matters more. |
Set only when this option is part of the intended request; otherwise omit it and let YaCy use the page default. |
Example request shape:
GET /yacysearch.html?query=climate+data&maximumRecords=10&resource=local&contentdom=text&verify=iffresh
What To Expect
The response is an HTML result page. It contains result entries, navigators/facets when enabled, and hidden references used by authenticated result actions. If a query returns too little, first check whether the crawler has indexed the relevant site and whether urlmaskfilter, collection, or contentdom narrowed the request too far.
Related Pages
Status.html