Get Started with GNews API
This page takes you from sign-up to your first request, then helps you choose the endpoint that fits.
What is GNews API?
GNews API is a real-time news API for developers. Search articles or get top headlines by category from 80,000+ sources in 41 languages and 71 countries, returned as JSON. Top headlines are based on Google News rankings.
The code examples in this documentation are in cURL, Python, JavaScript, PHP, and C#.
Quick start guide
1. Create your account
- Sign up for free. No credit card needed.
- Verify your email address with the code we email you. If you sign up with Google, your email address will be verified automatically.
- Copy your API key from the dashboard.
2. Make your first request
Every request follows this pattern:
GEThttps://gnews.io/api/v4/{endpoint}?{parameters}&apikey=YOUR_API_KEYTry this one in your browser or terminal:
GEThttps://gnews.io/api/v4/search?q=AI&lang=en&apikey=YOUR_API_KEY3. Choose your endpoint
Looking for articles about a topic? Use the Search endpoint to find articles that match your query.
Need today's top headlines? Use the Top Headlines endpoint, based on Google News rankings.
The two endpoints
Search endpoint
Finds articles that match your query, with filters for:
- Your query, with exact phrases, parentheses, and the AND, OR, and NOT operators
- Language and country
- Publication date range
Top Headlines endpoint
Returns the top headlines by category, language, and country, based on Google News rankings. The categories are
general, world, nation, business, technology, entertainment, sports, science, and health.
Top Headlines endpoint reference
What your plan includes
Both endpoints are available on every plan. The plan sets how many articles each request returns and how far back you can go:
| Plan | Articles per request | Data freshness | Historical data | Full article content |
|---|---|---|---|---|
| Free | Up to 10 | 12-hour delay | Last 30 days | Cut to 250 characters |
| Paid plans | Up to 100 | Real-time | Since 2020 | Yes |
Your plan's historical data sets the range of the from and to parameters: see
Article Availability. Daily quotas, prices, and the full comparison are on the
Pricing page.
Next steps
OpenAPI specification
The whole API is described in an OpenAPI 3.1 specification. Import it into Postman or Insomnia, generate a client in your language, or give it to an AI agent as a tool definition.
Support
- GitHub (opens in a new tab): official libraries and sample projects
- Contact us: questions about your plan, your account, or an integration
- FAQ: answers to common questions
Get your API key
Sign up for free to get your API key and make your first request.