> For the complete documentation index, see [llms.txt](https://docs.alpha-lenz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-lenz.com/ko/api-reference/public-api/research.md).

# Research API

증권사 리서치 리포트에 액세스합니다.

**필요 스코프:** `read:research` 또는 `read:all`

## 리서치 리포트 목록 조회

필터링 및 페이지네이션과 함께 리서치 리포트를 조회합니다.

```
GET /api/public/v1/research/reports
```

### Query Parameters

| 파라미터                | 타입      | 설명                                                   |
| ------------------- | ------- | ---------------------------------------------------- |
| `page`              | integer | 페이지 번호 (기본값: 1)                                      |
| `page_size`         | integer | 페이지당 항목 수 (1-100, 기본값: 20)                           |
| `securities_firm`   | string  | 증권사별 필터링                                             |
| `stock_name`        | string  | 종목명별 필터링                                             |
| `report_type`       | string  | 유형별 필터링: "company\_analysis" 또는 "industry\_analysis" |
| `industry_category` | string  | 산업 카테고리별 필터링                                         |
| `start_date`        | date    | 시작 날짜 필터 (YYYY-MM-DD)                                |
| `end_date`          | date    | 종료 날짜 필터 (YYYY-MM-DD)                                |
| `title`             | string  | 리포트 제목에서 검색                                          |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/research/reports?stock_name=삼성전자&page_size=10" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "reports": [
    {
      "id": 456,
      "title": "Samsung Electronics - 4Q23 Preview",
      "report_date": "2024-01-10",
      "report_type": "company_analysis",
      "securities_firm": "미래에셋증권",
      "stock_name": "삼성전자",
      "industry_category": "반도체",
      "cdn_url": "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
    }
  ],
  "total": 125,
  "page": 1,
  "page_size": 10,
  "has_next": true
}
```

***

## 리서치 리포트 조회

특정 리서치 리포트의 상세 정보를 조회합니다.

```
GET /api/public/v1/research/reports/{report_id}
```

### Path Parameters

| 파라미터        | 타입      | 설명         |
| ----------- | ------- | ---------- |
| `report_id` | integer | 리서치 리포트 ID |

### 요청 예시

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/research/reports/456" \
     -H "X-API-Key: ak_your_key"
```

### 응답

```json
{
  "id": 456,
  "title": "Samsung Electronics - 4Q23 Preview",
  "report_date": "2024-01-10",
  "report_type": "company_analysis",
  "securities_firm": "미래에셋증권",
  "stock_name": "삼성전자",
  "industry_category": "반도체",
  "s3_key": "reports/2024/01/456.pdf",
  "cdn_url": "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
}
```

### 리포트 다운로드

`cdn_url` 필드를 사용하여 PDF 리포트를 다운로드합니다:

```bash
curl -O "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
```

### 리포트 유형

| 유형                  | 설명       |
| ------------------- | -------- |
| `company_analysis`  | 개별 기업 분석 |
| `industry_analysis` | 산업/섹터 분석 |

### 페이지네이션

`page`와 `page_size`를 사용하여 페이지네이션을 구현합니다. `has_next`를 확인하여 추가 결과가 있는지 확인하세요:

```bash
# 첫 페이지
GET /research/reports?page=1&page_size=20

# 두 번째 페이지
GET /research/reports?page=2&page_size=20
```

### 필터링 예시

**증권사별:**

```
GET /research/reports?securities_firm=미래에셋증권
```

**날짜 범위별:**

```
GET /research/reports?start_date=2024-01-01&end_date=2024-01-31
```

**산업별:**

```
GET /research/reports?industry_category=반도체
```

**제목 검색:**

```
GET /research/reports?title=실적
```