# Google Search 모범 사례

더 많은 요청을 추가하기 전에 relevance 향상: 집중된 쿼리를 선택, 올바른 컨텍스트를 설정, 그리고 순위 순서에 유용한 소스를 유지.

Canonical 참고: https://flashdata.dev/ko/docs/guides/google-search-guide
검토: 2026-11-04 FlashData

<a id="query-patterns"></a>

## 질문에 대한 쿼리 일치

앱 또는 에이전트 프롬프트에서 지시를 작성하십시오. Google를 제출하고 필요한 사실. 전체 작업을 쿼리에 붙여 넣기 대신 몇 가지 집중 쿼리로 넓은 연구 작업을 분할합니다.

| 지원하다 | Query를 시도 |
| --- | --- |
| 측정된 결과 | battery recycling lithium recovery rates |
| 특정 게시자 | site:energy.gov battery recycling |
| 특정 구문 | "direct recycling" lithium-ion batteries |
| Fewer 관련 목록 | battery recycling -jobs -careers |


<a id="setup"></a>

## 1개의 기본 검색을 실행

API 키와 google_search 액세스 및 사용 가능한 크레딧을 사용하십시오. 제품 정보 Python 3.10+ 요청, 또는 Bash 으로 cURL. 두 탭은 동일한 단일 쿼리를 만들; 실행 하나. 예제는 google-first.json로 원시 응답을 저장합니다.

- [인증 설정](https://flashdata.dev/ko/docs/guides/google-search-guide/reference.md#authenticate)
- [CLI 사용자: 같은 요청 몸을 보내](https://flashdata.dev/ko/docs/guides/flashdata-cli/reference.md)

<a id="authenticate"></a>

### API 키 설정

이미 설정된 경우 FLASHDATA_API_KEY를 재사용합니다. 그렇지 않으면 코드를 실행할 터미널에서 숨겨진 프롬프트를 사용합니다. 에이전트는 비밀 저장소에서 같은 변수를로드 할 수 있습니다.

#### Bash

##### 키 설정

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```


#### PowerShell 7

##### 키 설정

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [API 키](https://flashdata.dev/app/api-keys)
- [에이전트 체험 및 계정 연결](https://flashdata.dev/ko/docs/guides/agent-onboarding/reference.md)

<a id="first-search"></a>

### 저장하고 요청을 실행

#### Python

새로운 작업 폴더에서 search.py를 생성하고 아래의 전체 Python 코드를 복사합니다. python search.py를 실행하기 전에 파일을 저장하십시오. 이 같은 폴더에 나중에 파일과 스크립트를 저장하십시오.

##### 한 번에 설치

```bash
python -m pip install requests
```

##### search.py

```python
# search.py — edit payload and filename for a deliberate new query.
import json
import os
import sys
from pathlib import Path
import requests

payload = {
    "source": "google_search",
    "query": "battery recycling recovery rates",
    "params": {
        "num": 5,
        "gl": "us",
        "hl": "en"
    }
}
if len(sys.argv) > 1:
    payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8-sig"))
output = Path(sys.argv[2] if len(sys.argv) > 2 else "google-first.json")
if output.exists():
    raise SystemExit(f"Read {output}, or choose a new output filename.")
response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json=payload, timeout=70, allow_redirects=False,
)
output.write_text(response.text, encoding="utf-8")
if response.status_code != 200:
    raise SystemExit(f"HTTP {response.status_code}; Retry-After: {response.headers.get('Retry-After')}")
data = response.json()
if data.get("status") != "done":
    raise SystemExit(f"Inspect {output} and History before retrying.")
print(json.dumps({"status": data["status"], "usage": data.get("usage")}, indent=2))
```

##### 실행

```bash
python search.py
```


#### cURL

##### Bash

```bash
# Bash; FLASHDATA_API_KEY must be set. Run one language tab, not both.
(
set -eu
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e google-first.json || { echo 'Read google-first.json first'; exit 1; }
curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"source":"google_search","query":"battery recycling recovery rates","params":{"num":5,"gl":"us","hl":"en"}}' \
  --output google-first.json
)
```



<a id="context"></a>

## 문제를 해결하는 필터 변경

한 번에 한 설정을 변경하고 다른 파일 이름 아래 각 새로운 응답을 저장하십시오. 이 요청 바디 예제는, 전체에서 실행하는 순서가 아닌.

### 국가 및 언어

gl 세트 국가 컨텍스트. hl 세트 인터페이스 언어, 엄격한 페이지 언어 필터; 당신의 대상 언어에 쿼리를 쓰기.

#### request.json

```json
{
  "source": "google_search",
  "query": "recyclage batteries lithium rendement",
  "params": { "num": 5, "gl": "fr", "hl": "fr" }
}
```


### 현지 결과

답변이 도시에 따라 달라지는 경우 위치. google_places를 사용하면 일반 웹 페이지보다 비즈니스 목록이 필요할 수 있습니다.

#### request.json

```json
{
  "source": "google_search",
  "query": "battery recycling companies",
  "params": { "num": 5, "gl": "us", "hl": "en",
    "location": "Austin, Texas, United States" }
}
```

- [장소 API](https://flashdata.dev/ko/docs/sources/google_places/reference.md)

### 최근 적용

tbs: qdr:w 요청 Google의 과거 주 필터. 최근 뭔가를 설명하기 전에 반환 페이지에 날짜를 체크하십시오. Retrieval 시간은 간행물이 아닙니다.

#### request.json

```json
{
  "source": "google_search",
  "query": "battery recycling pilot plant",
  "params": { "num": 5, "tbs": "qdr:w" }
}
```

- [뉴스 API](https://flashdata.dev/ko/docs/sources/google_news/reference.md)

### 기술 용어

제품 정보 autocorrect: false deliberate 맞춤법 또는 식별자가 쿼리 수정을 살아야 할 때. 그것은 모든 결과를 보장하지 않습니다 그 용어.

#### request.json

```json
{
  "source": "google_search",
  "query": "\"LiFePO4\" direct recycling",
  "params": {
    "num": 5,
    "autocorrect": false
  }
}
```


- [모든 Google Search 매개 변수](https://flashdata.dev/ko/docs/sources/google_search/reference.md#parameters)

<a id="apply-filter"></a>

### 선택된 요청을 실행

request.json로 하나의 탭의 JSON를 저장합니다. 아래 하나의 명령을 선택하고 각 변경된 요청에 대한 새 출력 파일 이름을 사용하십시오.

#### Python

##### 위에 저장되는 search.py를 사용하십시오

```bash
python search.py request.json google-filtered.json
```


#### cURL

##### Bash

```bash
curl --fail-with-body --silent --show-error --max-time 70 \
  --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json --output google-filtered.json
```



<a id="results"></a>

## 사용 가능한 소스를 유지, 그냥 결과 수 없습니다

google-first.json 옆에 read-results.py를 저장하고, 저장된 응답에 대하여 그 폴더에서 실행합니다. 그것은 결과 순서를 보존하고 정확한 URLs는, 중복을 제거하고, 시작 파일, 순위 및 사용법을 유지합니다. 그것은 빈 성공적인 결과를 받아들입니다. URL 쿼리 매개 변수를 스트립하지 마십시오 : 그들은 다른 페이지를 식별 할 수 있습니다.

| (주) | 사용하기 |
| --- | --- |
| 제목 및 스니펫 | 어떤 페이지를 읽을 수 있습니다. 그들은 전체 페이지 증거가 아닙니다. |
| 페이지의 순위 | 보존 된 구매 순서; 순위는 사실적인 confidence 점수가 아닙니다. |
| usage.credits | 실제 쿼리 비용 기록. num은 요청 예산이 아닌 결과 제한입니다. |

### read-results.py

```python
# read-results.py — no API calls; accepts one or more saved response files.
import json
import sys
from pathlib import Path
from urllib.parse import urlparse

sources, seen, usage = [], set(), []
for filename in (sys.argv[1:] or ["google-first.json"]):
    data = json.loads(Path(filename).read_text(encoding="utf-8-sig"))
    if data.get("status") != "done" or not isinstance(data.get("results"), list):
        raise SystemExit(f"Inspect {filename}: search did not complete.")
    usage.append({"file": filename, "usage": data.get("usage")})
    for rank, item in enumerate((data["results"] or [{}])[0].get("organic", []), 1):
        url = item.get("link", "")
        if url in seen or urlparse(url).scheme not in ("https", "http"):
            continue
        seen.add(url)
        sources.append({"title": item.get("title", ""), "url": url,
                        "snippet": item.get("snippet", ""),
                        "rankOnPage": rank, "responseFile": filename})
print(json.dumps({"sources": sources, "usage": usage}, indent=2))
```

### 다른 쿼리없이 읽음

```bash
python read-results.py google-first.json
```


<a id="pagination"></a>

## 다른 요청이 유용할지 결정

requests.post 전에 페이지를 추가하고 존재 확인 전에 출력 할당을 대체합니다. 모든 페이지는 별도의 쿼리입니다. 다음 페이지가 새로운 유용한 URLs에 기여하지 않는 경우 중지; num 및 페이지는 전체 인덱스 적용을 보장하지 않습니다.

| 첫 번째 결과 | 다음 이동 |
| --- | --- |
| 관련 소스는 질문을 덮습니다 | 검색을 중지하고 그 페이지를 읽으십시오. |
| 가장 관련한 페이지 | 질화하기 전에 쿼리 또는 컨텍스트를 정의합니다. |
| 결과 없음 | 대부분의 제한 연산자 또는 필터를 제거하십시오. 동일한 요청을 반복하지 마십시오. |
| 좋은 결과, 그러나 충분한 적용 | 호출 예산 내에서 쿼리 및 필터 교환 및 요청 페이지 2를 유지하십시오. |

### Python · search.py의 이러한 라인을 변경

```python
payload["params"]["page"] = 2
output = Path("google-page-2.json")
```


<a id="merge-pages"></a>

### 저장된 페이지를 Merge

#### 페이지 주문 유지 · API 통화 없음

```bash
python read-results.py google-first.json google-page-2.json
```

- [Batch 여러 알려진 쿼리](https://flashdata.dev/ko/docs/reference/batch-and-bulk/reference.md#batch)

<a id="choose"></a>

## 당신이 필요로 하는 결과를 일치하는 근원을 사용하십시오

위의 예는 유기 웹 결과를 사용합니다. 뉴스 기사, 제품 목록 및 지역 사업에는 다른 분야가 있습니다; 작업이 구조에 필요한 경우 스위치 소스.

- [뉴스](https://flashdata.dev/ko/docs/sources/google_news/reference.md)
- [이미지](https://flashdata.dev/ko/docs/sources/google_images/reference.md)
- [쇼핑](https://flashdata.dev/ko/docs/sources/google_shopping/reference.md)
- [동영상](https://flashdata.dev/ko/docs/sources/google_videos/reference.md)
- [장소](https://flashdata.dev/ko/docs/sources/google_places/reference.md)

<a id="agent"></a>

## 에이전트 검색에 대한 멈춤 규칙을 적용

이미 FlashData 액세스가 있는 에이전트와 이 작업을 사용합니다. 런너의 통화 제한을 강화하십시오. 프롬프트는 의도한 행동을 설명합니다.

### 에이전트 작업

```text
배터리 재활용 회수율에 대한 증거를 찾아보세요. num: 5를 가진 대부분의 2개의 Google Search 쿼리에 사용. 시작 집중; 정제 또는 파그네트 여부를 결정하기 전에 첫 번째 응답을 검사합니다. 질문이 덮거나 예산이 도달 할 때 정지. 정확한 URLs, 결과 주문 및 사용법을 보존하십시오. 선택된 페이지를 읽고, 지원된 발견을 인용하고, 누락된 증거를 보고하십시오. 검색 순위를 자신감이나 검색 텍스트로 취급하지 마십시오.
```

- [검색 기능 구축](https://flashdata.dev/ko/docs/guides/search-in-an-app/reference.md)
- [웹 및 비디오 증거 결합](https://flashdata.dev/ko/docs/guides/google-youtube-research/reference.md)

<a id="operations"></a>

## 요청 모드 및 복구

공유된 API 기본을 사용하여 작업 polling, 일괄 처리 봉투, 응답 형식 및 복원 결정. 이 예제는 자동 복원하지 않습니다 : 네트워크 타임 아웃은 여전히 쿼리를 제출 할 수 있으므로 반복하기 전에 History를 검사합니다.

- [Realtime 또는 동기화?](https://flashdata.dev/ko/docs/reference/realtime-and-async/reference.md#choose)
- [Batch 요청](https://flashdata.dev/ko/docs/reference/batch-and-bulk/reference.md#batch)
- [오류 코드 및 retries](https://flashdata.dev/ko/docs/errors/reference.md#retries)
- [응답 형식](https://flashdata.dev/ko/docs/guides/response-formats/reference.md#headers)
- [비율 제한](https://flashdata.dev/ko/docs/guides/usage-and-limits/reference.md#rate-limit)
