> For the complete documentation index, see [llms.txt](https://help.genser.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genser.ai/developers/action-data/api-references/search.md).

# 검색 (Search)

검색 관련 사용자 행동 수집 API

## 검색 제출

> 검색 제출 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"검색 (Search)","description":"검색 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"},{"url":"https://api-dev.gelatto.ai","description":"Development"},{"url":"http://localhost","description":"Local Development (포트 80)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsSearchSubmittedEvent":{"title":"검색 제출","description":"사용자가 검색어를 제출하는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-SEARCH-SUBMITTED"]},"type":{"type":"string","description":"이벤트 유형","enum":["search_submitted"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/search_submitted.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","query"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["SearchAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"query":{"type":"string","description":"검색어"},"object":{"type":"object","description":"대상 객체","required":["actionOption"],"properties":{"@type":{"type":"string","enum":["Thing"]},"actionOption":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"액션 옵션"}}},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}}}},"paths":{"/actions/search/submitted":{"post":{"summary":"검색 제출","description":"검색 제출 수집 API","operationId":"collectSearchSubmitted","tags":["검색 (Search)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsSearchSubmittedEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```

## 검색 결과 노출

> 검색 결과 수집 API

```json
{"openapi":"3.1.0","info":{"title":"젤라또 이벤트 수집 API (기본)","version":"1.0.0"},"tags":[{"name":"검색 (Search)","description":"검색 관련 사용자 행동 수집 API"}],"servers":[{"url":"https://api.gelatto.ai","description":"Production"},{"url":"https://api-dev.gelatto.ai","description":"Development"},{"url":"http://localhost","description":"Local Development (포트 80)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API 키"}},"schemas":{"ActionsSearchResultEvent":{"title":"검색 결과 노출","description":"사용자에게 검색 결과가 노출되는 행동을 수집합니다","type":"object","required":["time","source","data"],"properties":{"specversion":{"type":"string","description":"스펙 버전","enum":["1.0.0"]},"id":{"type":"string","description":"이벤트 고유 식별자","enum":["EVT-VIEW-SEARCH-RESULT"]},"type":{"type":"string","description":"이벤트 유형","enum":["view_search_result"]},"time":{"type":"string","description":"ISO 8601 UTC 이벤트 생성시간","format":"date-time"},"source":{"type":"string","description":"이벤트 발생 출처"},"datacontenttype":{"type":"string","description":"데이터 콘텐츠 타입","enum":["application/ld+json"]},"dataschema":{"type":"string","description":"데이터 스키마 경로","enum":["https://api.gelatto.ai/schema/actions/search_result.json"]},"data":{"type":"object","description":"이벤트 데이터 객체","required":["agent","object"],"properties":{"@context":{"type":"string","description":"스키마 context","enum":["https://schema.org/"]},"@type":{"type":"string","description":"액션 유형","enum":["ViewAction"]},"agent":{"type":"object","description":"행위자 (Person)","required":["identifier"],"properties":{"@type":{"type":"string","enum":["Person"]},"identifier":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"type":"string","description":"값"}}},"type":"array","description":"행위자 식별자 목록 (userId, memberId, cookieId는 필수로 추가해야 함, 속성의 추가가 필요할 경우 협의)"},"gender":{"type":"string","enum":["Female","Male","https://schema.org/Female","https://schema.org/Male"]},"additionalProperty":{"items":{"type":"object","required":["propertyID","value"],"properties":{"@type":{"type":"string","enum":["PropertyValue"]},"propertyID":{"type":"string","description":"속성 ID"},"value":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"값"}}},"type":"array","description":"추가 속성"}}},"object":{"$ref":"#/components/schemas/ActionsSearchResultItemList"},"target":{"type":"object","description":"엔드포인트 정보","required":["urlTemplate"],"properties":{"@type":{"type":"string","enum":["EntryPoint"]},"urlTemplate":{"type":"string","description":"URL"}}}}}}},"ActionsSearchResultItemList":{"description":"상품 목록 객체","type":"object","required":["numberOfItems","itemListElement"],"properties":{"@type":{"type":"string","enum":["ItemList"]},"numberOfItems":{"type":"number","description":"검색 결과 총 건수"},"itemListElement":{"oneOf":[{"$ref":"#/components/schemas/ActionsSearchResultListItem"},{"type":"array","items":{"$ref":"#/components/schemas/ActionsSearchResultListItem"}}]}}},"ActionsSearchResultListItem":{"description":"상품 목록 항목","type":"object","required":["position","item"],"properties":{"@type":{"type":"string","enum":["ListItem"]},"item":{"$ref":"#/components/schemas/ActionsSearchResultProduct"},"position":{"type":"number","description":"목록 내 노출 순서"}}},"ActionsSearchResultProduct":{"description":"상품 객체","type":"object","required":["sku"],"properties":{"@type":{"type":"string","enum":["Product"]},"sku":{"type":"string","description":"상품 고유 식별자, 상품코드 (SKU)"},"name":{"description":"상품명","oneOf":[{"description":"단순 문자열","type":"string"},{"description":"다국어 객체","type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}},{"description":"다국어 배열","type":"array","items":{"type":"object","required":["@value","@language"],"properties":{"@value":{"type":"string","description":"상품명 값"},"@language":{"type":"string","description":"ISO 639-1 언어코드","enum":["ko","en","ja"]}}}}]}}}}},"paths":{"/actions/search/result":{"post":{"summary":"검색 결과 노출","description":"검색 결과 수집 API","operationId":"collectSearchResult","tags":["검색 (Search)"],"parameters":[{"name":"Content-Type","in":"header","required":true,"schema":{"type":"string","enum":["application/json"]},"description":"콘텐츠 타입"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid"},"description":"멱등성 키 - 클라이언트가 호출 시 전달해야 함 (UUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionsSearchResultEvent"}}}},"responses":{"200":{"description":"수집 성공"},"400":{"description":"잘못된 요청"},"503":{"description":"서비스 일시 이용 불가"}}}}}}
```