[ TMDB ] API search 엔드포인트 사용하기

 

 

 

TMDB API 홈

https://developer.themoviedb.org/reference/intro/getting-started

Getting Started

 

 

 

📺 TMDB API: search 엔드포인트 사용하기

 

API KEY 발급

https://euntry.tistory.com/55?category=1174358

[ TMDB ] API KEY 발급하기

 

 

TMDB API 를 사용할려면 API 키를 발급 받아야 한다

 

 

API Base Url

https://api.themoviedb.org/3

 

 

Image Base Url

https://image.tmdb.org/t/p/original

 

 

요청 헤더 

Header	설명
Authorization	Bearer {API_KEY}
Content-Type	application/json

 

 

🔎 /search/movie 엔드포인트

영화 제목으로 검색

 

HTTP 요청

GET /search/movie?query={query}&api_key={API_KEY}

 

필수 파라미터
query	검색할 영화 제목
api_key	API Key
선택 파라미터
include_adult	성인용 콘텐츠 포함 여부 (기본값: false)
language	언어 (기본값: en-US, 한국: ko-KR)
primary_release_year	특정 개봉 연도 (숫자, 4자리)
page	결과 페이지 (기본값: 1)
region	지역코드 (ISO 3166-1 형식, 한국: KR)
year	특정 제작 연도 (숫자, 4자리)

 

 

reponse Data

{
  "page": 1,    // 결과 페이지 번호
  "results": [
    {
        "adult": false,     // 성인용 콘텐츠 여부
        "backdrop_path": "/yHzyPJrVqlTySQ9mc379yxrLBYQ.jpg",    // 백드롭 이미지 경로
        "genre_ids": [
            12,
            14
        ],  // 장르 ID 
        "id": 672,  // 영화 고유 ID
        "original_language": "en",  // 영화의 원어 코드
        "original_title": "Harry Potter and the Chamber of Secrets",    // 영화의 원래 제목
        "overview": "해리 포터에겐 이번 여름방학이 별로 즐겁질 못했다...",   // 요약 설명
        "popularity": 160.846,  // 영화의 인기 지수
        "poster_path": "/sfs4U6XpiKFngbbSzrpZbkM1ySI.jpg",  // 포스터 이미지 경로
        "release_date": "2002-11-13",   // 개봉일
        "title": "해리 포터와 비밀의 방",   // 지역화된 영화 제목
        "video": false, // 비디오 콘텐츠 여부
        "vote_average": 7.716,  // 평균 평점
        "vote_count": 22002 // 평가 수
    }
  ],
  "total_pages": 1, // 총 페이지 수
  "total_results": 1    // 전체 검색 건수
}

 

 

🔎 /search/tv 엔드포인트

TV 프로그램 제목으로 검색

 

HTTP 요청

GET /search/tv?query={query}&api_key={API_KEY}

 

필수 파라미터
query	검색할 TV 프로그램 제목
api_key	API Key
선택 파라미터
include_adult	성인용 콘텐츠 포함 여부 (기본값: false)
language	언어 (기본값: en-US, 한국: ko-KR)
first_air_date_year	첫 방영 연도 (숫자, 4자리)
page	결과 페이지 (기본값: 1)
year	모든 에피소드 방영 연도 (숫자, 4자리)

 

 

reponse Data

{
    "page": 1,
    "results": [
        {
            "adult": false,
            "backdrop_path": "/s2qJb1FLwp1Mse9lY08JqgMp0kw.jpg",
            "genre_ids": [
                10764,
                35
            ],
            "id": 5092,
            "origin_country": [
                "KR"
            ], // TV 프로그램 제작 국가
            "original_language": "ko",
            "original_name": "무한도전", // TV 프로그램의 원래 제목
            "overview": "대한민국 평균 이하임을 자처하는 남자들이 매주 새로운 상황 속에서 펼치는 좌충우돌 도전기",
            "popularity": 254.15,
            "poster_path": "/fpXfEfcZu5uDTOKqjwXSGgrL4iY.jpg",
            "first_air_date": "2005-04-23", // 첫 방영일
            "name": "무한도전", // 제목
            "vote_average": 7.6,
            "vote_count": 19
        }
    ],
    "total_pages": 1,
    "total_results": 1
}

 

 

 

🔎 /search/person 엔드포인트

인물 성명으로 검색

 

HTTP 요청

GET /search/person?query={query}&api_key={API_KEY}

 

필수 파라미터
query	검색할 인물 성명
api_key	API  Key
선택 파라미터
include_adult	성인용 콘텐츠와 연관된 인물 포함 여부 (기본값: false)
language	언어 (기본값: en-US, 한국: ko-KR)
page	결과 페이지 (기본값: 1)

 

 

reponse Data

{
    "page": 1,
    "results": [
        {
            "adult": false,
            "gender": 1, // 성별 (1:여성, 2:남성, 0: 지정되지 않음)
            "id": 10990,
            "known_for_department": "Acting", // 주로 활동하는 분야
            "name": "엠마 왓슨",
            "original_name": "Emma Watson",
            "popularity": 69.298,
            "profile_path": "/mf0OANvWYSzU1d8yggrhyw8IbIz.jpg",
            "known_for": [ // 대표작(영화, TV프로그램)
                {
                    "backdrop_path": "/uU1Mt4JWhDvl4vKb3AfxNsorkoM.jpg",
                    "id": 321612,
                    "title": "미녀와 야수",
                    "original_title": "Beauty and the Beast",
                    "overview": "프랑스의 작은 마을에 아버지와 살고 있는 벨은 책을 통해...",
                    "poster_path": "/tzYsKo6wGoBrP51eL9wDzfDP6Vx.jpg",
                    "media_type": "movie", // 미디어 구분 (movie 혹은 tv)
                    "adult": false,
                    "original_language": "en",
                    "genre_ids": [
                        10751,
                        14,
                        10749
                    ],
                    "popularity": 84.905,
                    "release_date": "2017-03-16",
                    "video": false,
                    "vote_average": 6.97,
                    "vote_count": 15419
                },
            ]
        }
    ],
    "total_pages": 1,
    "total_results": 1
}

 

 

 

🔎 /search/multi 엔드포인트

영화, TV 프로그램 제목 혹은 인물 성명으로 검색

 

HTTP 요청

GET /search/multi?query={query}&api_key={API_KEY}

 

필수 파라미터
query	검색어
api_key	API Key
선택 파라미터
include_adult	성인용 콘텐츠 포함 여부 (기본값: false)
language	언어 (기본값: en-US, 한국: ko-KR)
page	결과 페이지 (기본값: 1)

 

 

reponse Data

영화, TV 프로그램, 인물을 구분할 수 있는 media_type 값에 따라 반환되는 필드가 달라진다

영화 검색, TV 프로그램 검색, 인물 검색의 응답 형식을 기반으로 하며, 기존의 각 검색 결과 구조에 media_type 필드가 포함된 형태로 반환된다

{
    "page": 1,
    "results": [
        {
            "media_type": "", // 미디어 구분 (movie, tv, person)
        },
    ],
    "total_pages": 1,
    "total_results": 1
}