Your First Search with NewsAPI.ai — Exploring the Sandbox

From registration to your first live query

If you’ve already created your free account, you’re ready for the fun part — seeing NewsAPI.ai in action. If not, start with our first guide: “Getting Started with NewsAPI.ai”. It walks you through creating your account and claiming 2,000 free searches you can use anytime, with no time limit.

Once you’re logged in and on your dashboard, you’ll see a tile labeled “Sandbox page.” Click it to open your personal testing environment — the place where you’ll run your very first query.

1. What is the Sandbox?

The Sandbox is an interactive playground that lets you explore the NewsAPI.ai endpoints without any setup. Everything you do here is live — you’re working with real data from global sources, using your own free searches.

It’s perfect for experimenting:

• Build and test queries visually.
• See the response structure instantly.
• Export ready-to-run code for your app or analysis environment.

2. Getting familiar with the interface

On the left-hand side, you’ll see the main API sections, including:

• Most used
• Text analytics
• Articles
• Events
• Event Types
• Autosuggest
• Other helper endpoints

For your first run, we’ll stay with Articles -> Get articles — the most used and simplest endpoint for seeing results quickly.

3. Explore how searches work

You can create your searches in three different ways, depending on how you want NewsAPI.ai to interpret your query:

• Simple Search Mode — Google-like search where not all entered keywords need to be present in the results.
• Exact Search Mode — Search where all entered keywords must appear in the results. Use AND, OR, NOT, NEXT/X, and NEAR/X operators to get precise combinations.
• Concept Search Mode — Search based on the meaning of the words (including synonyms and disambiguated entities) rather than exact keywords.

For most users, Concept Search Mode is the best place to start. It’s the most powerful and most commonly used option because it understands meaning, not just text — recognizing entities such as companies, people, or topics automatically and filtering out irrelevant matches.

To see how it works in practice, try one of the sample queries displayed at the top of the Sandbox. All examples in this guide use Concept Search Mode, and each highlights a different focus or filter.

You’ll see examples like:

• News about Apple Inc. reported by top business-related news sources, sorted by relevance — focuses on a company concept and filters by source relevance.
• Spanish articles about football that had the highest number of shares on social media — combines language and social engagement filters.
• News about sustainability in all available languages — a broad multilingual search for a global topic.
• Recent negative news from Israel and Palestine reporting about their conflict — demonstrates sentiment filtering and regional coverage.

When you click on any of these, the search query field fills automatically. Take a moment to observe how it’s structured — the concepts, the relations between them, and the filters applied for source, time, or sentiment. This gives you a good sense of how to prepare your own query.

Then, simply click Execute Search to run it and see live results appear.

4. Your first query

Now that you’ve seen how sample queries work, it’s time to create your own.

Don’t worry — your first query can be simple. You’ll be using the same fields and filters you just explored, this time with your own topic.

In the Get articles view, you’ll see the “Your search query” field with sample queries above it.

Type: Tesla, Inc. (or any topic or company you care about).

Below, you’ll see Response Configuration — this controls how results are returned.

For this first walkthrough, a simple setup works best:

• Sort results by: Date, Relevance, or Social media shares — depending on what matters most for your test.
• Return type: List of articles

This gives you a straightforward list of the latest articles.

If you want to explore later, the Return type dropdown also lets you switch to things like Top concepts, Tag cloud, Timeline, Top news sources, Languages, Concept graph, Article categories, Recent activity, and more — all based on the same query.

Under Returned info for → Article, the default selection includes:

• Basic information
• Title
• Body
• Event URI

This is ideal for your first test — you see actual content.If needed, you can also include concepts, categories, locations, images, videos, extracted links/dates, duplicate info, social scores, and original article URLs by ticking additional fields.

Click Execute Search.

You’ve just run a real query against NewsAPI.ai using the Sandbox.

Each search retrieves results from the last 30 days, using the same enrichment pipeline available through the API.

5. Refining your results with filters

Right under the query bar, you’ll see filter options such as:

• Locations – limit results to specific countries or regions.
• Sources – include or exclude particular publishers.
• Categories – focus on topics like business, tech, environment, etc.
• Date – adjust the time window (e.g. last month, last week, or any range within the 30-day limit).
• Language – choose a single language or keep it broader.
• Misc. – additional controls:
  • Data type: News / PR / Blogs
  • Duplicate filters: include only original or also duplicate content
  • Event filtering: choose whether to display only articles that are part of an identified event, only those that aren’t, or both (default shows all)
  • Minimum shares on social media
  • Sentiment slider: restrict to more positive or more negative content

Combine these to shape a precise feed. For example:

Show English-language news about Tesla, Inc., from the last month, tagged as News, without duplicates.

Run the search again with your chosen filters.

6. Exploring the output

Once your query runs, the Sandbox shows results in two synchronized views:

Visual display

A clean list of article cards where you can quickly see:

• Title
• Snippet
• Source name
• Time of publication
• Basic indicators

This is great for quickly checking if your query and filters return what you expect.

Returned JSON response

Switch to the Returned JSON response tab to see the full structured output exactly as your application would receive it.

At the top of the response, you’ll see general metadata such as:

• totalResults
• page, count, pages

Below that, each article appears as an object containing fields similar to the example you tested.
A typical article includes:

• uri – the internal ID of the article
• lang – article language
• isDuplicate – whether this article is labeled as a duplicate
• date, time, dateTime, dateTimePub – publication timestamps
• dataType – “news”, “blog”, or “pr”
• url – the link to the original article
• title – article title
• body – article text (if returned info includes body)
• source – an object containing:
  • uri – the source domain
  • dataType – type of publisher
  • title – readable source name
• authors – list of article authors (if available)
• concepts – extracted entities such as people, companies, and locations
• image – main image URL (if detected)
• eventUri – event this article belongs to, if grouped
• shares – social media share count (if available)
• sentiment – sentiment score
• wgt – internal weight score
• relevance – relevance score relative to your query

The exact fields you see depend on what you select under “Returned info for → Article,” but this is the typical structure of a NewsAPI.ai article response.

This view shows how NewsAPI.ai enriches every article — combining source metadata, timestamps, concepts, sentiment, and relevance into a structured format ready for immediate analysis or integration into your workflow.

7. Generate ready-to-use code

Below the results, click Generate Code to see how this exact query looks as an API call.

You can instantly view and copy implementations for:

• REST
• JavaScript
• PHP
• Node.js
• Python

The generated snippet includes:

• The correct endpoint
• Your query parameters
• The structure of the request body

So you can go from “this works in the Sandbox” to “this runs in my codebase” in one step.

For reference:

• Python SDK: github.com/EventRegistry/event-registry-python
• Node.js SDK: github.com/EventRegistry/event-registry-node-js

Next steps

You’ve just built and run your first query — and seen how easy it is to customize results with filters, output settings, and code generation.

From here, you can:

• Try Get events to group coverage around specific developments.
• Explore Event Types for structured business, risk, or policy signals.
• Keep experimenting using your 2,000 free searches.

Open the Sandbox and try your own topic. Prefer a guided walkthrough? Book a demo.