APITube Documentation
Sign inGet started

Filter News by Reading Level ​

Use readability filters to choose articles for language learners, children, general readers or specialists. See Readability Filters for all parameters.

Step 1: Pick a difficulty band ​

Choose a readability.difficulty: beginner (below grade 6), intermediate (6–10), advanced (10–14) or expert (14+). Or select an audience with readability.audience: children, general, professional or academic.

bash
curl "https://api.apitube.io/v1/news/everything?readability.difficulty=beginner&language.code=en&per_page=20&api_key=YOUR_API_KEY"
python
import requests

response = requests.get(
    "https://api.apitube.io/v1/news/everything",
    params={
        "readability.difficulty": "beginner",
        "language.code": "en",
        "per_page": "20",
        "api_key": "YOUR_API_KEY",
    },
)
print(response.json())
javascript
const params = new URLSearchParams({ "readability.difficulty": "beginner", "language.code": "en", "per_page": "20", "api_key": "YOUR_API_KEY" });
const response = await fetch(`https://api.apitube.io/v1/news/everything?${params}`);
const data = await response.json();
console.log(data);
php
$query = http_build_query(["readability.difficulty" => "beginner", "language.code" => "en", "per_page" => "20", "api_key" => "YOUR_API_KEY"]);
$response = file_get_contents("https://api.apitube.io/v1/news/everything?$query");
$data = json_decode($response, true);
print_r($data);
go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	u, _ := url.Parse("https://api.apitube.io/v1/news/everything")
	q := u.Query()
	q.Set("readability.difficulty", "beginner")
	q.Set("language.code", "en")
	q.Set("per_page", "20")
	q.Set("api_key", "YOUR_API_KEY")
	u.RawQuery = q.Encode()

	resp, _ := http.Get(u.String())
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	var data map[string]any
	json.Unmarshal(body, &data)
	fmt.Println(data)
}
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.apitube.io/v1/news/everything?readability.difficulty=beginner&language.code=en&per_page=20&api_key=YOUR_API_KEY"))
            .GET()
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
text
Write a script in your preferred language that calls the APITube News API:

GET https://api.apitube.io/v1/news/everything?readability.difficulty=beginner&language.code=en&per_page=20

Read the API key from an environment variable (do not hardcode it), handle request
errors, and print the key fields of each result.
Docs: https://docs.apitube.io/platform/news-api/everything

Each article carries the scores it was matched on, so you can show them in the UI:

json
{
    "readability": {
        "flesch_kincaid_grade": 8,
        "flesch_reading_ease": 100,
        "automated_readability_index": 8.8,
        "difficulty_level": "intermediate",
        "target_audience": "general",
        "reading_age": 13,
        "avg_words_per_sentence": 60.5
    }
}
  • Grade level — readability.flesch_kincaid_grade, the US school grade needed to follow the text.
  • Ease score — readability.flesch_reading_ease, 0–100, where higher is easier.
  • Reading age — readability.reading_age, in years.
  • Difficulty and audience — readability.difficulty_level and readability.target_audience use the same values as the filters.

Step 2: Set a precise range for reading level ​

To set a more precise reading level, use numeric filters with .min and .max: readability.fk_grade (0–30), readability.ease (0–100), readability.ari (0–30) or readability.age (6–22).

bash
curl "https://api.apitube.io/v1/news/everything?readability.fk_grade.min=6&readability.fk_grade.max=10&readability.ease.min=60&language.code=en&per_page=20&api_key=YOUR_API_KEY"
python
import requests

response = requests.get(
    "https://api.apitube.io/v1/news/everything",
    params={
        "readability.fk_grade.min": "6",
        "readability.fk_grade.max": "10",
        "readability.ease.min": "60",
        "language.code": "en",
        "per_page": "20",
        "api_key": "YOUR_API_KEY",
    },
)
print(response.json())
javascript
const params = new URLSearchParams({ "readability.fk_grade.min": "6", "readability.fk_grade.max": "10", "readability.ease.min": "60", "language.code": "en", "per_page": "20", "api_key": "YOUR_API_KEY" });
const response = await fetch(`https://api.apitube.io/v1/news/everything?${params}`);
const data = await response.json();
console.log(data);
php
$query = http_build_query(["readability.fk_grade.min" => "6", "readability.fk_grade.max" => "10", "readability.ease.min" => "60", "language.code" => "en", "per_page" => "20", "api_key" => "YOUR_API_KEY"]);
$response = file_get_contents("https://api.apitube.io/v1/news/everything?$query");
$data = json_decode($response, true);
print_r($data);
go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	u, _ := url.Parse("https://api.apitube.io/v1/news/everything")
	q := u.Query()
	q.Set("readability.fk_grade.min", "6")
	q.Set("readability.fk_grade.max", "10")
	q.Set("readability.ease.min", "60")
	q.Set("language.code", "en")
	q.Set("per_page", "20")
	q.Set("api_key", "YOUR_API_KEY")
	u.RawQuery = q.Encode()

	resp, _ := http.Get(u.String())
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	var data map[string]any
	json.Unmarshal(body, &data)
	fmt.Println(data)
}
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.apitube.io/v1/news/everything?readability.fk_grade.min=6&readability.fk_grade.max=10&readability.ease.min=60&language.code=en&per_page=20&api_key=YOUR_API_KEY"))
            .GET()
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
text
Write a script in your preferred language that calls the APITube News API:

GET https://api.apitube.io/v1/news/everything?readability.fk_grade.min=6&readability.fk_grade.max=10&readability.ease.min=60&language.code=en&per_page=20

Read the API key from an environment variable (do not hardcode it), handle request
errors, and print the key fields of each result.
Docs: https://docs.apitube.io/platform/news-api/everything

Two shortcuts cover the common cases without any numbers: is_easy_read=1 keeps articles with a Flesch Reading Ease of 60 or above, and is_difficult_read=1 keeps everything below 40.

Step 3: Set a reading-time limit and add other filters ​

Combine readability and read_time to choose articles your readers can understand and finish in the time available. Then add topic or other filters.

bash
curl "https://api.apitube.io/v1/news/everything?readability.difficulty=beginner&read_time.max=3&language.code=en&category.id=medtop:15000000&per_page=20&api_key=YOUR_API_KEY"
python
import requests

response = requests.get(
    "https://api.apitube.io/v1/news/everything",
    params={
        "readability.difficulty": "beginner",
        "read_time.max": "3",
        "language.code": "en",
        "category.id": "medtop:15000000",
        "per_page": "20",
        "api_key": "YOUR_API_KEY",
    },
)
print(response.json())
javascript
const params = new URLSearchParams({ "readability.difficulty": "beginner", "read_time.max": "3", "language.code": "en", "category.id": "medtop:15000000", "per_page": "20", "api_key": "YOUR_API_KEY" });
const response = await fetch(`https://api.apitube.io/v1/news/everything?${params}`);
const data = await response.json();
console.log(data);
php
$query = http_build_query(["readability.difficulty" => "beginner", "read_time.max" => "3", "language.code" => "en", "category.id" => "medtop:15000000", "per_page" => "20", "api_key" => "YOUR_API_KEY"]);
$response = file_get_contents("https://api.apitube.io/v1/news/everything?$query");
$data = json_decode($response, true);
print_r($data);
go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	u, _ := url.Parse("https://api.apitube.io/v1/news/everything")
	q := u.Query()
	q.Set("readability.difficulty", "beginner")
	q.Set("read_time.max", "3")
	q.Set("language.code", "en")
	q.Set("category.id", "medtop:15000000")
	q.Set("per_page", "20")
	q.Set("api_key", "YOUR_API_KEY")
	u.RawQuery = q.Encode()

	resp, _ := http.Get(u.String())
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	var data map[string]any
	json.Unmarshal(body, &data)
	fmt.Println(data)
}
java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.apitube.io/v1/news/everything?readability.difficulty=beginner&read_time.max=3&language.code=en&category.id=medtop:15000000&per_page=20&api_key=YOUR_API_KEY"))
            .GET()
            .build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
text
Write a script in your preferred language that calls the APITube News API:

GET https://api.apitube.io/v1/news/everything?readability.difficulty=beginner&read_time.max=3&language.code=en&category.id=medtop:15000000&per_page=20

Read the API key from an environment variable (do not hardcode it), handle request
errors, and print the key fields of each result.
Docs: https://docs.apitube.io/platform/news-api/everything

For a learning app, offer several difficulty levels so users can move up as they improve:

python
import requests

LEVELS = {
    "A2": {"readability.fk_grade.max": 5},
    "B1": {"readability.fk_grade.min": 5, "readability.fk_grade.max": 8},
    "B2": {"readability.fk_grade.min": 8, "readability.fk_grade.max": 11},
    "C1": {"readability.fk_grade.min": 11},
}

def feed(level, api_key, language="en", limit=20):
    params = {"language.code": language, "per_page": limit, "api_key": api_key, **LEVELS[level]}
    return requests.get("https://api.apitube.io/v1/news/everything", params=params).json()["results"]

Tip: readability scores apply to each article. Filter by the score to find a reading level across different publishers.