> 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=실적
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alpha-lenz.com/ko/api-reference/public-api/research.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.