Question 1

How do I authenticate with this API?

Accepted Answer

Subscribe to a plan on this API pricing page, then send your JoJ API key on every request.

Use this header: X-JoJAPI-Key: YOUR_API_KEY

These also work: Authorization: Bearer YOUR_API_KEY Authorization: YOUR_API_KEY

The gateway checks the key and removes it before forwarding. Do not put the key in the URL or in the JSON body.

Question 2

Which countries are supported?

Accepted Answer

The country parameter is required. Use a lowercase code: en, ko, au, nz, it, ja, gb, fr, de, in.

Examples: en is USA, ko is Korea, gb is United Kingdom, ja is Japan.

Question 3

How do I choose a news section?

Accepted Answer

The section parameter is optional. If you omit it, you get all sections for that country.

Common values: top, BUSINESS, ENTERTAINMENT, SPORTS, WORLD, HEALTH.

For it, ko, ja, fr, de use SCITECH. For en, au, nz, gb, in use SCIENCE and TECHNOLOGY.

TOP is treated as top. For several sections on GET, use a comma list such as BUSINESS,SPORTS. On POST you may send a JSON array.

Question 4

How do I call the API? GET or POST?

Accepted Answer

Both GET and POST work. Use the gateway URL shown on this API page.

GET example: GET /queryNews?country=ko&section=top

POST example body: {"country":"en","section":["top","BUSINESS"]}

If country or section is invalid, the API returns HTTP 400. The JSON has errorCode INVALID_REQUEST and the allowed values in message.

Question 5

What does a successful response look like?

Accepted Answer

A success response has status success and a data object.

data.country is the country you requested. data.sections is the section list you requested. An empty list means every section was returned. data.count is how many News documents were returned. data.items is the document list. Each item has docId, code, id, updatedAt, and news.

news is the article array. Typical fields: title, link, url, img, content, summary, section. title and link may look like an object with a _text field.

Usage for that call is also in gateway response headers for the Request API object.

Question 6

Why is summary empty for some articles?

Accepted Answer

AI summaries are filled for de, en, and ko. Other countries return summary as an empty string.

summary can also be empty when the source page had no usable article body.

Question 7

How often is the news updated?

Accepted Answer

The News collection is synced about every 5 minutes. updatedAt on each document is a Unix timestamp in milliseconds.

Question 8

How is usage billed and what are the quotas?

Accepted Answer

This API bills the Request API object (request-api). One successful request costs 1 unit, even if you omit section and receive every section for a country.

Fixed monthly quotas, unused units do not carry over: Free: 150 per month 10 USD: 5,000 per month 29 USD: 20,000 per month 79 USD: 80,000 per month

Rate limits are on the pricing page for each plan. HTTP 5xx and gateway-generated errors do not consume quota.

Question 9

What do 401, 402 and 400 mean?

Accepted Answer

401 means the JoJ API key is missing or invalid, or you have no active subscription. Subscribe on the pricing page and send X-JoJAPI-Key.

402 is billing. quota_exceeded means the Request API quota is used up. not_included means the plan does not cover that object. insufficient_balance means the pay-as-you-go wallet is empty.

400 from this API (not the gateway) means country or section is invalid. Check that country is present, that it is one of en, ko, au, nz, it, ja, gb, fr, de, in, and that the section is valid for that country. For example, SCIENCE is not used with ko (use SCITECH). SCITECH is not used with en (use SCIENCE or TECHNOLOGY).

Gateway-made errors include the header X-Jojapi-Gateway-Response: true.

Neper News

Frequently Asked Questions