yacy_search_server/help/ConfigSearchBox.md

---
page: htroot/ConfigSearchBox.html
help: help/ConfigSearchBox.md
title: Integration of a Search Box
package: configuration-administration
access: mixed
kind: search-page
backend_java: source/net/yacy/htroot/ConfigSearchBox.java
---

# Integration of a Search Box

## Purpose

Integration of a Search Box generates embeddable search-box code for another website. It helps turn this YaCy peer into the search backend for a page that lives somewhere else.

Use it when visitors should type a query on an external site and receive results from `yacysearch.html` on this peer.

## What You Can Do Here

- Generate or inspect the HTML snippet for an external search box.
- Understand that the generated form submits to `yacysearch.html`, so the real search parameters are the same as the search page.
- Use the snippet only after choosing the target peer address and expected result behavior.

## Page Architecture

This page is an integration helper. It shows the HTML form code for a search box and demonstrates the target request that the form will send to `yacysearch.html`. The controls on this page are not a separate search engine; they are a compact front door into the normal YaCy search endpoint.

## Correct Use

Use the generated code as a template, then adapt the surrounding site HTML outside YaCy. Keep the form action pointed at the YaCy peer that should answer searches, and keep the query field named `query`. If the external page should search only a collection or site, add the same search parameters documented for `yacysearch.html`.

## 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: administrator authentication, user authentication.

## Automation And API

Page backend: `source/net/yacy/htroot/ConfigSearchBox.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.

| 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 it to request later result 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 request context for date handling. |
| `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=...&maximumRecords=...&resource=...&contentdom=...&Enter=...
```

## What To Expect

The page provides an embeddable snippet or demonstration form. The actual user search happens later when a visitor submits the form and YaCy receives a `yacysearch.html` request.

## Related Pages

- Related configuration work is usually reached from `ConfigBasic.html`, `Settings_p.html`, or the adjacent configuration page in the administration menu.