# 빠른 시작

첫 Google 검색을 실행하고 앱이나 AI 에이전트에서 사용할 구조화된 결과를 받아 보세요.

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

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

## AI 에이전트로 시작하기

터미널을 사용할 수 있는 에이전트에게 이 프롬프트를 전달하세요. 에이전트가 FlashData를 설정하고 검색 한 건을 실행합니다.

### 설정 및 첫 작업 프롬프트

```text
https://flashdata.dev/auth.md를 읽고 이 환경에 맞는 FlashData 설정 지침을 따르세요. 기존 접근 권한을 재사용하고, 없는 경우에만 자격 요건을 충족하는 체험을 한 번 시작하세요. Google에서 "battery recycling research"를 검색해 최대 다섯 개의 결과를 가져오세요. 출처 제목, URL 및 실제 사용한 크레딧을 반환하세요. 인증 정보는 보호된 저장소에 보관하고 채팅에 표시하지 마세요. 접근이 차단되면 다른 체험을 만들지 말고 다음에 필요한 단계를 알려 주세요.
```

- [MCP 설정](https://flashdata.dev/ko/docs/integrations/mcp-clients/reference.md)
- [에이전트 스킬](https://flashdata.dev/ko/docs/guides/agent-skill/reference.md)

<a id="application"></a>

## 첫 API 호출 실행

직접 코드를 작성하려면 터미널에서 다음 세 단계를 진행하세요.


<a id="api-key"></a>

### API 키 받기

계정을 만들고 이메일을 인증한 뒤 Google Search 권한이 있는 키를 생성하세요. 이미 키가 있다면 재사용하세요.

터미널에서 실행한 뒤 입력이 숨겨지는 프롬프트에 키를 붙여 넣으세요. 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
```


- [계정 만들기](https://flashdata.dev/signup)
- [API Keys 열기](https://flashdata.dev/app/api-keys)

<a id="request"></a>

### 검색 실행

언어를 선택하고 같은 터미널에서 예제를 실행하세요. 실행할 때마다 검색 한 건이 제출됩니다.

#### Python

Python 3.10+ · 예제를 quickstart.py로 저장하세요.

##### 설치

```bash
python -m pip install "flashdata==1.1.0"
```

##### quickstart.py

```python
import json
import os
from flashdata import FlashData

with FlashData(api_key=os.environ["FLASHDATA_API_KEY"]) as client:
    response = client.google.search("battery recycling research", num=5)
    if response["status"] != "done":
        raise RuntimeError(response)
    print(json.dumps(response, indent=2))
```

##### 실행

```bash
python quickstart.py
```


#### TypeScript

Node.js 22.18+ · 빈 폴더에서 시작하고 quickstart.mts로 저장하세요.

##### 설정

```bash
npm init -y
npm install --save-exact @flashdata-dev/sdk@1.1.0
```

##### quickstart.mts

```typescript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.google.search({
  query: 'battery recycling research', num: 5,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(JSON.stringify(response, null, 2));
```

##### 실행

```bash
node quickstart.mts
```


#### JavaScript

Node.js 22+ · 빈 폴더에서 시작하고 quickstart.mjs로 저장하세요.

##### 설정

```bash
npm init -y
npm install --save-exact @flashdata-dev/sdk@1.1.0
```

##### quickstart.mjs

```javascript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.google.search({
  query: 'battery recycling research', num: 5,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(JSON.stringify(response, null, 2));
```

##### 실행

```bash
node quickstart.mjs
```


#### Go

Go 1.25+ · 빈 폴더에서 시작하고 main.go로 저장하세요. 기존 모듈에서는 go mod init을 건너뛰세요.

##### 설정

```bash
go mod init example.com/flashdata-quickstart
go get github.com/flashdatadev/flashdata-go@v1.1.0
```

##### main.go

```go
package main

import (
    "context"
    "encoding/json"
    "log"
    "os"
    "time"

    flashdata "github.com/flashdatadev/flashdata-go"
)

func main() {
    key := os.Getenv("FLASHDATA_API_KEY")
    if key == "" {
        log.Fatal("Set FLASHDATA_API_KEY through your server's secret manager.")
    }
    client, err := flashdata.New(flashdata.Options{APIKey: key})
    if err != nil {
        log.Fatal(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
    defer cancel()
    result, err := client.Google.Search(ctx, flashdata.GoogleSearchInput{
        Query: "battery recycling research",
        Params: &flashdata.GoogleSearchParams{Num: flashdata.Ptr(int64(5))},
    })
    if err != nil {
        // Do not automatically resubmit an uncertain paid request.
        log.Fatal(err)
    }
    if err := json.NewEncoder(os.Stdout).Encode(result); err != nil {
        log.Fatal(err)
    }
    if result.Status != "done" {
        log.Fatalf("Search did not complete: %s", result.Status)
    }
}
```

##### 실행

```bash
go run .
```


#### HTTP API

SDK가 필요하지 않습니다. Bash / cURL 7.76+ 또는 PowerShell 7 명령을 실행하세요.

##### Bash / cURL

```bash
curl --fail-with-body --silent --show-error \
  --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 research","params":{"num":5}}'
```

##### PowerShell 7

```powershell
$flashdataRequest = '{"source":"google_search","query":"battery recycling research","params":{"num":5}}'
$flashdataResult = Invoke-RestMethod -Method Post -Uri 'https://data.flashdata.dev/v1/queries/realtime' -Headers @{ 'X-API-Key' = $env:FLASHDATA_API_KEY } -ContentType 'application/json' -Body $flashdataRequest
$flashdataResult | ConvertTo-Json -Depth 20
```


- [아래에서 결과 확인](https://flashdata.dev/ko/docs/guides/quickstart/reference.md#result)

<a id="result"></a>

### 결과 확인

성공한 응답에는 status: done이 표시됩니다. 출처는 results[].organic에, 사용한 크레딧은 usage.credits에 있습니다.

#### 응답 예제(일부)

```json
{
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Battery recycling research",
          "link": "https://example.org/recycling",
          "snippet": "An example search excerpt."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  }
}
```

- [검색 개선하기](https://flashdata.dev/ko/docs/guides/google-search-guide/reference.md)
- [YouTube Data 사용해 보기](https://flashdata.dev/ko/docs/guides/youtube-data-guide/reference.md)
- [API 설정 및 문제 해결](https://flashdata.dev/ko/docs/guides/http-quickstart/reference.md)

<a id="console"></a>

## 콘솔에서 사용해 보기

1. 계정 또는 로그인을 만듭니다. 콘솔에 표시된 모든 계정 설정 완료.
2. Google Search를 열고, Google Search 소스와 Realtime 모드를 선택하고, 배터리 재활용 연구를 입력합니다. 추가 매개 변수를 확장하고 5에 페이지 크기 (num)를 설정합니다.
3. 표시된 요청 및 사용 가능한 크레딧을 확인한 후 검색을 한 번 실행합니다.
4. 응답과 사용법을 검사합니다. 반환된 소스를 열고 그 발췌보다 더 인용하기 전에 내용을 확인합니다.

- [계정 만들기](https://flashdata.dev/signup)
- [오픈 Google Search](https://flashdata.dev/app/google-search)

<a id="next"></a>

## 첫 결과 다음 단계

- [필터로 검색](https://flashdata.dev/ko/docs/guides/google-search-guide/reference.md)
- [YouTube 데이터 살펴보기](https://flashdata.dev/ko/docs/guides/youtube-data-guide/reference.md)
- [앱에 검색 추가](https://flashdata.dev/ko/docs/guides/search-in-an-app/reference.md)

<a id="troubleshooting"></a>

## 첫 요청이 실패한 경우

| 증상 | 해결 방법 |
| --- | --- |
| FLASHDATA_API_KEY가 설정되지 않음 | 예제를 실행하는 터미널이나 런타임에서 키를 설정하세요. 이 예제는 .env 파일을 읽지 않습니다. |
| 401 / 403 | 키 또는 연결이 활성 상태이고 google_search 권한이 있는지 확인하세요. |
| 402 | Billing에서 사용 가능한 크레딧을 확인하세요. 소유자 접근 권한이 필요하다면 기존 체험을 계정에 연결하세요. |
| 429 | Retry-After를 따르세요. 동일한 식별 정보와 등록 증명을 유지하고 다른 체험을 만들지 마세요. |
| 시간 초과 또는 제출 여부 불확실 | 다시 시도하기 전에 기존 실행을 확인하세요. CLI에서는 같은 프로필과 실행 ID를 유지하고, SDK/API에서는 반환된 작업 ID 또는 요청 ID를 저장하세요. |

