path: root/help/yacysearch.md

---
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:

```http
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`