README

An unofficial PHP client to retrieve news data from the G1 website, a property of Globo Comunicação e Participações S.A..

This project is intended strictly for educational and study purposes. It has no commercial intent and does not claim ownership of any content retrieved from G1.

The goal is to provide a simple, structured, and developer-friendly way to access Brazilian news metadata programmatically.

Features

Fetch latest news headlines from G1
Filter news by Brazilian state (UF)
Pagination support
Structured responses via typed objects
Optional filesystem cache with configurable TTL

Note This is not an official API and may break if G1 changes its internal structure.

Installation

Install via Composer:

composer require adaiasmagdiel/g1-client

Basic Usage

<?php

require_once __DIR__ . '/vendor/autoload.php';

use AdaiasMagdiel\G1\Client;
use AdaiasMagdiel\G1\Enum\Estado;

// Initialize the client (cache enabled by default)
$api = new Client();

// Fetch latest news from all regions
$resAll = $api->ultimas();
echo $resAll->news[0]->title . PHP_EOL;

// Fetch latest news from a specific state (e.g., Pará)
$resPara = $api->ultimas(estado: Estado::PARA);
echo $resPara->news[0]->title . PHP_EOL;

// Fetch page 2 of the latest news
$resPage2 = $api->ultimas(page: 2);
echo $resPage2->news[0]->title . PHP_EOL;

Cache Configuration

The client includes an optional filesystem cache.

Enable cache (default)

$api = new Client(
    cache: true,
    cacheDir: __DIR__ . '/.g1-cache',
    cacheTtl: 600 // seconds
);

Disable cache entirely

$api = new Client(cache: false);

When disabled:

No filesystem access
No cache reads or writes
All requests hit the network directly

Cache Usage Recommendation

⚠️ Important Notice

Although the cache can be fully disabled, this is strongly discouraged in production or frequent usage scenarios.

Disabling the cache causes:

A significantly higher number of HTTP requests to G1 servers
Slower response times
Increased risk of temporary blocks or rate limiting
Unnecessary load on a third-party service

For this reason, it is highly recommended to keep the cache enabled whenever possible, especially when:

Fetching multiple pages
Iterating through states (Estado::cases())
Building dashboards, feeds, or automated tools

The cache exists to:

Reduce network traffic
Improve performance
Be respectful to the source website

Use the cache responsibly.

Working with News Items

The response returned by ultimas() is an instance of Ultimas, which contains a news array.

Each item in news is an instance of News with the following properties:

Property	Description
`url`	Full URL of the news article
`id`	Unique identifier
`feedId`	Feed identifier
`type`	Content type (e.g. `materia`)
`created`	Creation timestamp (ISO 8601)
`modified`	Last modification timestamp
`isPublishing`	Indicates if the item is currently publishing
`images`	Array of available image sizes (`XS`, `S`, `M`, `L`, etc.)
`chapeu`	Editorial label metadata
`section`	Section name (e.g. São Paulo, Política)
`title`	Main headline
`recommendationTitle`	Optimized title for recommendations
`summary`	Article summary
`recommendationSummary`	Optimized summary

Example: Accessing an image

$img =
    $news->images['S']['url']
    ?? $news->images['M']['url']
    ?? $news->images['L']['url']
    ?? null;

Legal Notice

This project:

Is not affiliated with Globo
Does not redistribute copyrighted content
Only consumes publicly available metadata
Exists for learning, testing, and research purposes

Use responsibly.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You are free to use, modify, and distribute this software under the terms of the GPLv3. Any derivative work must also be distributed under the same license.

See the LICENSE file for full details.

adaiasmagdiel / g1-client

Maintainers

Details