Frequently Asked
Questions

GNews API is a REST API that lets you search and retrieve news articles from over 80,000 sources worldwide. Results come back as clean, structured JSON, so you can build news feeds, monitoring dashboards, market and brand tracking, research datasets, or AI pipelines without running your own crawler.

Create an account at gnews.io/register, confirm your email address, and your API key is waiting on your dashboard. It works immediately on the Free plan, no credit card required.

Call an endpoint over HTTPS with your API key and read the JSON response. For example: https://gnews.io/api/v4/search?q=example&lang=en&apikey=YOUR_API_KEY. You can also build and run requests without writing any code from the API Playground in your dashboard. The full parameter reference is in the documentation.

Two. Search (/api/v4/search) runs a full-text query across articles, with boolean operators, date ranges, language and country filters, sorting and pagination. Top Headlines (/api/v4/top-headlines) returns the current top stories for a category such as general, world, nation, business, technology, entertainment, sports, science or health. Both are documented at docs.gnews.io.

No. The Free plan is available as soon as your account is activated and never asks for payment details. A card is only needed when you start a paid plan or a free trial of one.

Plans differ by daily request quota, the number of articles returned per request and access to real-time and historical data. Free gives 100 requests/day and 10 articles per request, with a 12-hour delay and 30 days of history. Essential gives 1,000 requests/day and 25 articles, Business 5,000 requests/day and 50 articles, Enterprise 25,000 requests/day and 100 articles. Every paid plan includes real-time articles, history back to 2020, full article content, CORS for all origins and email support. The full comparison is on the pricing page.

Every paid plan comes with a 10-day free trial that unlocks all of its features. Start it from Change plan; you will be asked for a payment method but nothing is charged during the trial, and cancelling before it ends costs you nothing. The trial is available once per account.

No. The Free plan is for non-commercial projects, development and testing only. Commercial and published projects need a paid plan. Accounts that abuse these terms are terminated.

Yearly billing saves 20% compared to paying monthly: Essential is €479.99 per year instead of €599.88, Business €959.99 instead of €1,199.88, and Enterprise €2,399.99 instead of €2,999.88. Switch between monthly and yearly with the toggle on the pricing page.

Custom plans build on the Enterprise plan: you can raise the daily request quota and the number of articles returned per request, choose your support level, and ask for features we do not offer as standard. Write to contact@gnews.io or use the contact form with the volume and the features you need. Custom plans are paid only and start above what Enterprise already includes.

GNews API indexes more than 80,000 news sources, covering 41 languages and 71 countries. The exact language and country codes accepted by each endpoint are listed in the documentation, since the Search and Top Headlines endpoints do not accept the same sets.

Our archive goes back to 2020. Paid plans can query the whole archive with the from and to parameters. On the Free plan, results are limited to the last 30 days; older articles are removed from the response and the API tells you how many were dropped.

On every paid plan, articles are available in real time, as soon as they are indexed. The Free plan has a 12-hour delay: articles published in the last 12 hours are not returned.

Yes, on paid plans the content field contains the full text of the article. On the Free plan the content is truncated to a short excerpt. You can also request a truncated excerpt on any plan by adding truncate=content to your request.

Not yet. Source filtering is on our roadmap. In the meantime, every article carries its source object (name, homepage URL and, on the Search endpoint, country), so you can filter or group results on your side.

By default, only articles with all attributes filled in are returned. Some publishers do not provide a summary or a cover image, and those articles are excluded unless you opt in with the nullable parameter, for example nullable=image,description. Use it when you want maximum coverage and can handle missing fields.

totalArticles is the number of articles matching your query; the response only contains one page of them. Raise max (up to the limit of your plan: 10 on Free, 25 on Essential, 50 on Business, 100 on Enterprise) and walk through the results with page. Pagination stops at 1,000 articles per query, so narrow the query with filters or a date range to go deeper.

Google News rankings decide which stories make it into a category, so the selection reflects what is actually leading the news cycle for the category, language and country you request. The articles themselves are then returned in chronological order, newest first.

Yes. Data retrieved through the API may be used commercially on any paid plan. You remain responsible for respecting third-party copyright: article text and images belong to their publishers, and you must not present the data as your own. The Free plan is the exception, it is for development and testing only. See our Terms of Service for the full conditions.

Attribution is appreciated but not required, unless your plan specifically states otherwise.

Send it through the form on our Sources page. Include the URL of the source and, if you can, its name and country of origin. Submitting several at once is fine, just list them in the message.

Either add your key to the query string as apikey=YOUR_API_KEY, or send it in the X-Api-Key HTTP header. The header is the better choice on a server, as the key then stays out of logs and referrer headers. A missing or invalid key returns 401 Unauthorized.

The q parameter accepts up to 200 characters and supports quoted phrases for an exact match, AND, OR, NOT and parentheses for grouping. Two words separated by a space are combined with AND by default, and OR binds more tightly than AND, so use parentheses when you mix them. Remember to URL-encode the query. On the Search endpoint, in=title,description,content controls which fields are searched.

• 400 - the request is malformed; check parameter names, values and query syntax.
• 401 - the API key is missing or invalid.
• 403 - your daily quota is used up; it resets at 00:00 UTC.
• 429 - too many requests per second; throttle your calls or back off and retry.
• 500 - an error on our side; retry shortly.
• 503 - temporary maintenance; retry in a few minutes.

Once the daily limit is reached, the API answers 403 Forbidden and returns no more data until the counter resets, which happens every day at 00:00 UTC. Unused requests do not carry over to the next day. You can follow your usage on your dashboard, and upgrade at any time from Change plan if you need more headroom.

Yes: 1 request per second on the Free plan and 10 requests per second on every paid plan. Going over that returns 429 Too Many Requests, so spread out bursts or retry with exponential backoff.

Yes on any paid plan, where CORS is enabled for all origins. On the Free plan, CORS only allows localhost, so browser requests from a deployed site are blocked. Keep in mind that a key used in front-end code is visible to anyone, so for a public site it is safer to call the API from your own backend and forward the results.

Open the Account page, click the refresh icon next to the API key field, then confirm. The new key works immediately and the old one stops working at that very moment, so the two never overlap: anything still calling the API with the old key gets 401 Unauthorized until you deploy the new one. Rotate when you are ready to update your projects right away, and copy the new key from the same page.

No. It is a plain REST API over HTTPS, so any HTTP client works. The official libraries simply save you from writing the request building, authentication and error handling yourself.

A JavaScript/TypeScript package covering Node.js, React and Vue.js, and a PHP package that also works with Laravel. Both are listed with their install instructions on the Libraries & SDKs page.

Yes. Our MCP server exposes GNews API to LLMs and AI agents, so your assistant can search and read live news with structured results. It works with any MCP-compatible client and uses your normal API key.

Gladly. Send us the repository or package URL through the form on the Libraries & SDKs page. We review community projects and showcase the ones that are documented and maintained.

1. Go to Change plan, from the sidebar or from the Plan & Billing page.
2. Pick the plan and the billing frequency you want.
3. Review the billing summary shown in the confirmation window, then confirm.

The change takes effect immediately, and your new limits apply to your next request.

Your invoice is prorated, so you only pay for what you use. Upgrading charges the prorated cost of the remaining days on the new plan right away. Downgrading credits the unused part of your current plan to your account balance, which is then applied automatically to future invoices. Switching from monthly to yearly applies prorated costs and starts a new annual billing cycle. Every adjustment is detailed in the invoices on your Plan & Billing page.

Yes, at any time and at no extra cost:

1. Open Plan & Billing.
2. In the Subscription section, click Cancel subscription.
3. Tell us in a few words why you are leaving, then confirm.

You keep full access until the end of the period you have already paid for, and your account then returns to the Free plan. Changed your mind before that date? Click Resume subscription on the same page. Cancelling during a free trial means you are never charged.

Nothing: your key and your account stay as they are, and your requests keep working under the Free plan limits, with a 12-hour delay, 30 days of history and 100 requests per day. Subscribe again whenever you want and the paid limits come back on the same key.

Stripe retries the payment up to 4 times over two weeks, and you are emailed at each attempt. Updating your payment method on the Plan & Billing page during that window keeps your subscription alive. If every attempt fails, the subscription is cancelled and the account is downgraded automatically.

Payments are processed by Stripe. Credit and debit cards are accepted everywhere, and any additional method Stripe enables for your country appears on the checkout page. Your payment details are handled by Stripe and never reach our servers.

You can request a refund within 7 days of your initial subscription or of a renewal, provided you have not made any API call in that period. Email contact@gnews.io with a short explanation; we review requests within 3 to 5 business days and approved refunds usually reach your account 5 to 10 business days later. Requests we consider fraudulent or abusive may be denied. Full details are in our Terms of Service.

First request a new verification email from your dashboard and check your spam folder, as the link in older emails expires. If it still does not work, write to contact@gnews.io from the address you signed up with and we will activate the account for you.

Use gnews.io/forgot-password and we will email you a reset link. If you are already signed in, you can change your password directly from the Account page. Accounts created with Google sign-in have no password: sign in with Google instead.

1. If you have an active subscription, cancel it first on the Plan & Billing page and wait until the paid period is over.
2. Open the Account page and click Delete account.
3. Type DELETE in the confirmation field and confirm.

Deletion is permanent: your API key stops working and all data attached to the account is erased.

Email contact@gnews.io or use the contact form. Paid plans include email support, and Enterprise customers get premium support.

We answer most messages within one business day. Including the email address of your account, the plan you are on and, for a technical issue, the exact request URL with the API key removed and the response you received, usually gets your problem solved in a single reply.

Students, researchers and teaching staff working on an academic project, a thesis or coursework at a recognised institution. Requests are reviewed individually, and an institutional email address makes the review much faster.

Free access to a plan built on our Essential tier: 1,000 requests per day, up to 25 articles per request, real-time article availability, historical data back to 2020, full article content, access to all sources, CORS enabled for all origins and email support.

1. Create your free account at gnews.io/register.
2. Fill in the form at the bottom of this page from your student email address.
3. Describe your project or research and the institution you are attending.

We review each request manually and reply by email with the next steps once your plan is ready.

No. Education access is granted for academic and learning projects. If your project starts generating revenue or ships as a commercial product, move to a standard paid plan; write to contact@gnews.io and we will help you transition.

You keep your free account, and you are welcome to reply to our email with more detail about your project or institution so we can reconsider. Our paid plans, all with a 10-day free trial, remain available on the pricing page.

Mostly for the ratio between volume and price: paid plans start at €49.99 per month for 1,000 requests per day, with real-time articles, history back to 2020 and full article content included rather than sold as add-ons. You also get access to all 80,000+ sources on every plan and email support with a fast response time.

Usually an afternoon of work. There are two REST endpoints, authentication is a single API key, and the JSON response is flat: totalArticles plus an articles array whose items carry title, description, content, url, image, publishedAt, lang and a source object. Most migrations amount to swapping the base URL, renaming a few query parameters and remapping those fields. The documentation and the official libraries cover the rest.

Yes, in two steps: start on the Free plan to check the shape of the data and your integration, then run a 10-day free trial of a paid plan to test it with real-time articles, full content and production volumes. You can cancel at any point during the trial without being charged.

No. Google retired its public News API, leaving developers without an official way to query Google News programmatically. GNews API was built to fill that gap with the pieces people actually relied on: ranked top headlines, full-text search, filters by language and country, and predictable JSON.

No. GNews API is an independent service and is not affiliated with, endorsed by or sponsored by Google. Our Top Headlines endpoint follows Google News rankings to decide which stories are leading, but the service, the infrastructure and the support are entirely our own.

Because scraping breaks. Layouts change, requests get blocked, articles need deduplicating and normalising, and none of it is legally comfortable. GNews API gives you a stable, documented contract instead: one API key, two endpoints, consistent JSON, and article content already extracted and cleaned.