README

Laravel package to fetch the bus timetables of Grodno (Belarus) inside your application, by scraping the source website grodno.btrans.by — without hosting or calling any external API.

PHP port of the scraper originally written in Python (bus-schedule/). Same data structure, same caching strategy (7 days) as the original API.

Features

List every available bus route.
Directions and stop sequence for a route (/avtobus/{id}).
Detailed weekday / weekend schedule for a (route, stop) pair.
Connections: which buses serve a given stop.
Alphabetical reference of every stop.
Built-in Laravel caching (7 days by default) so the source website is never overloaded.

Installation

composer require yannxtrem/grodno-bus-schedule

For Laravel >= 9, the ServiceProvider and the BusSchedule facade are auto-discovered.

Publish the config (optional):

php artisan vendor:publish --tag=grodno-bus-schedule-config

Usage

Via the facade

use BusSchedule;

$buses = BusSchedule::getAllBuses();          // list of bus routes
$route = BusSchedule::getBusSchedule('1');    // stops and directions of bus 1
$stops = BusSchedule::getAllStops();          // list of every stop

Via dependency injection

use Yannxtrem\GrodnoBusSchedule\BusSchedule;

class TransportController
{
    public function index(BusSchedule $schedule)
    {
        return $schedule->getBusesAtStop('mehanicheskij-zavod');
    }
}

Public API

Method	Description	Cache key
`getAllBuses()`	List of bus routes (`bus_number`, `bus_id`, `url`)	`all_buses_list`
`getBusSchedule(string $busId)`	Directions + stops of a route	`bus_route_{busId}`
`getStopSchedule(string $busId, string $stopSlug)`	Weekday/weekend schedule of a stop	`schedule_{busId}_{stopSlug}`
`getBusesAtStop(string $stopSlug)`	Buses serving a stop	`stop_buses_{stopSlug}`
`getAllStops()`	Alphabetical list of stops	`all_stops_global_list`
`forget(string $key)`	Remove a cache key	—

Every method returns the same data structure as the original API:

[
  'status' => 'success',
  'count'  => 45,
  'buses'  => [
     ['bus_number' => '1', 'bus_id' => '1', 'url' => 'https://grodno.btrans.by/avtobus/1'],
     // ...
  ],
]

On network or parsing errors: ['status' => 'error', 'message' => '...']. A non-existent stop returns Stop not found (404).

Typical flow

// 1. Find a stop
$stops = BusSchedule::getAllStops();
$stop  = collect($stops['stops'])->firstWhere('slug', 'mehanicheskij-zavod');

// 2. Which buses stop there?
$buses = BusSchedule::getBusesAtStop($stop['slug']);      // ["1", "15", "20", ...]

// 3. Schedule for a (route, stop) pair
//    (the long slug comes from getBusSchedule, e.g. mehanicheskij-zavod-030)
$schedule = BusSchedule::getStopSchedule('1', 'mehanicheskij-zavod-030');
// => ['weekdays' => ['05:52', '06:52', ...], 'weekends' => ['06:15', ...]]

Caching

Caching is enabled by default and uses your application's default cache store.

GRODNO_BUS_CACHE_ENABLED=true
GRODNO_BUS_CACHE_TTL=604800      # 7 days, in seconds
GRODNO_BUS_CACHE_STORE=          # empty = default store
GRODNO_BUS_CACHE_PREFIX=grodno_bus_schedule

BusSchedule::forget('all_buses_list');          // invalidate a specific key
BusSchedule::forget('bus_route_1');

Warning: do not "poll" for real-time data. This package (like the original API) delivers theoretical timetables. The cache exists to be respectful of the source website: keep a long TTL.

Configuration

Available environment variables (see config/grodno-bus-schedule.php):

GRODNO_BTRANS_BASE_URL=https://grodno.btrans.by
GRODNO_BTRANS_PATH_AVTOBUS=avtobus
GRODNO_BTRANS_PATH_OSTANOVKA=ostanovka
GRODNO_BUS_HTTP_TIMEOUT=30
GRODNO_BUS_HTTP_CONNECT_TIMEOUT=10
GRODNO_BUS_HTTP_VERIFY=true

Using it for another city

If btrans.by publishes a similar website for another city, just change GRODNO_BTRANS_BASE_URL.

License

MIT — see LICENSE.

This package is not officially affiliated with btrans.by. Implement your own throttling and respect the usage rules of the source website.

yannxtrem / grodno-bus-schedule

Package info

Security

Statistics