국가별 뉴스 API로 헤드라인을 가져오는 방법

Neper는 국가와 섹션 단위로 뉴스를 모은다. 같은 데이터는 Neper News API로도 열려 있어서, 소스를 직접 긁지 않고도 헤드라인·기사 URL·이미지·요약을 앱에 넣을 수 있다.

엔드포인트는 /queryNews 하나다. 아래 마켓 중 하나를 통해 호출하면 되고, 요청 형태는 같다. 달라지는 것은 호스트와 인증 헤더뿐이다.

• RapidAPI
• JoJ API

Neper 가이드 모음에서 현재 API 안내와 이후 추가되는 Neper 문서를 함께 확인할 수 있다.

이미 쓰는 마켓에서 구독한 뒤, 그 마켓의 키로 /queryNews를 호출하면 된다.

1. 요청: country와 section

GET과 POST 모두 된다.

• country (필수): en, ko, au, nz, it, ja, gb, fr, de, in
• section (선택): 빼면 해당 국가의 모든 섹션을 받는다

자주 쓰는 섹션은 top, BUSINESS, ENTERTAINMENT, SPORTS, WORLD, HEALTH다.

과학·기술 섹션 id는 국가마다 다르다.

• it, ko, ja, fr, de → SCITECH
• en, au, nz, gb, in → SCIENCE 또는 TECHNOLOGY

TOP은 top으로 처리된다. GET에서는 BUSINESS,SPORTS처럼 쉼표로 여러 개를 넘기고, POST에서는 문자열·쉼표 문자열·JSON 배열을 쓸 수 있다.

예시:

GET /queryNews?country=en
GET /queryNews?country=ko&section=top
GET /queryNews?country=ko&section=SCITECH

{ "country": "gb", "section": ["SPORTS", "BUSINESS"] }

뉴스 문서는 대략 5분마다 갱신된다. updatedAt은 밀리초 단위 Unix 시각이다.

2. 응답 형태

성공 응답은 이런 식이다.

{
  "status": "success",
  "message": "Request successful",
  "data": {
    "country": "ko",
    "sections": ["top"],
    "count": 1,
    "items": [
      {
        "docId": "kotop",
        "code": "ko",
        "id": "top",
        "updatedAt": 1757116800000,
        "news": [
          {
            "title": { "_text": "Headline" },
            "link": { "_text": "https://news.google.com/rss" },
            "url": "https://example.com/article",
            "img": "https://example.com/image.jpg",
            "content": "Article body",
            "summary": "One-sentence summary",
            "section": "top"
          }
        ]
      }
    ]
  }
}

빠지기 쉬운 포인트만 정리하면 이렇다.

• section을 생략하면 data.sections는 빈 배열이고, 그 국가의 모든 섹션이 돌아온다.
• title, link는 _text 필드를 가진 객체일 수 있다. 화면에 넣기 전에 _text를 읽으면 된다.
• 기사에는 description, faviconUrl 같은 필드도 올 수 있다.
• AI summary는 de, en, ko에 채워진다. 다른 국가는 빈 문자열이다. 지원 국가라도 원문 본문을 못 읽으면 summary가 비어 있을 수 있다.

3. RapidAPI

1. RapidAPI 페이지에서 플랜을 구독한다.
2. 대시보드에서 RapidAPI 키를 복사한다.
3. RapidAPI 호스트로 호출한다. 키는 헤더에만 넣고, URL이나 JSON body에는 넣지 않는다.

https://neper-news-api.p.rapidapi.com

X-RapidAPI-Key: <YOUR_KEY>
X-RapidAPI-Host: neper-news-api.p.rapidapi.com

curl -G 'https://neper-news-api.p.rapidapi.com/queryNews' \
  --data-urlencode 'country=ko' \
  --data-urlencode 'section=top' \
  -H 'X-RapidAPI-Key: <YOUR_KEY>' \
  -H 'X-RapidAPI-Host: neper-news-api.p.rapidapi.com'

import axios from 'axios'

const res = await axios.get('https://neper-news-api.p.rapidapi.com/queryNews', {
  params: { country: 'ko', section: 'top' },
  headers: {
    'X-RapidAPI-Key': '<YOUR_KEY>',
    'X-RapidAPI-Host': 'neper-news-api.p.rapidapi.com'
  }
})

console.log(res.data)

const res = await axios.post(
  'https://neper-news-api.p.rapidapi.com/queryNews',
  { country: 'en', section: ['top', 'BUSINESS'] },
  {
    headers: {
      'X-RapidAPI-Key': '<YOUR_KEY>',
      'X-RapidAPI-Host': 'neper-news-api.p.rapidapi.com'
    }
  }
)

4. JoJ API

1. JoJ API 페이지에서 플랜을 구독한다.
2. JoJ API 키를 만들거나 복사한다.
3. 이 API용 JoJ 호스트로 호출한다. 게이트웨이가 키를 확인한 뒤 제거하고 요청을 넘긴다.

https://neper-news-api.jojapi.net

기본으로 쓰는 헤더:

X-JoJAPI-Key: <YOUR_KEY>

아래도 된다.

Authorization: Bearer <YOUR_KEY>
Authorization: <YOUR_KEY>

curl -G 'https://neper-news-api.jojapi.net/queryNews' \
  --data-urlencode 'country=ko' \
  --data-urlencode 'section=top' \
  -H 'X-JoJAPI-Key: <YOUR_KEY>'

import axios from 'axios'

const res = await axios.get('https://neper-news-api.jojapi.net/queryNews', {
  params: { country: 'ko', section: 'top' },
  headers: {
    'X-JoJAPI-Key': '<YOUR_KEY>'
  }
})

console.log(res.data)

const res = await axios.post(
  'https://neper-news-api.jojapi.net/queryNews',
  { country: 'en', section: ['top', 'BUSINESS'] },
  {
    headers: {
      'X-JoJAPI-Key': '<YOUR_KEY>'
    }
  }
)

JoJ API에서는 Request API 사용량으로 과금된다. 성공한 요청 한 번이 1단위다. section을 생략해 전 섹션을 받아도 마찬가지다. 월 쿼터와 rate limit은 요금 페이지를 보면 된다. HTTP 5xx와 게이트웨이가 만든 오류는 쿼터를 쓰지 않는다.

5. 오류

상태	보통 의미
400	country / section이 없거나 잘못됨. errorCode는 INVALID_REQUEST, 허용 값은 message에 있다.
401	키가 없거나 잘못됐거나, 활성 구독이 없음
402	JoJ API 과금 문제: 쿼터 소진, 플랜에 해당 오브젝트 없음, 잔액 부족
429	rate limit 또는 쿼터 초과
5xx	일시적인 서버 문제

JoJ API에서 게이트웨이가 만든 응답에는 X-Jojapi-Gateway-Response: true가 붙는다.

400이 자주 나는 경우는 과학 섹션 id를 섞는 경우다. ko에는 SCIENCE가 아니라 SCITECH, en에는 SCITECH이 아니라 SCIENCE 또는 TECHNOLOGY를 쓴다.

6. 마켓 선택

양쪽 모두 /queryNews 동작은 같다. 이미 RapidAPI에서 키와 결제를 관리 중이면 RapidAPI를, 여러 마켓 API를 하나의 JoJ 키·지갑으로 쓰고 싶으면 JoJ API를 쓰면 된다.

키는 소스에 넣지 않는다. JoJ에서 Neper만 쓴다면 키 접근 범위를 이 API로 제한하는 편이 낫다.

다른 지역이 필요하거나 연동 중 막히는 부분이 있으면 [email protected]으로 연락하면 된다.