PHPackages                             flerex/spain-gas - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. flerex/spain-gas

ActiveLibrary[API Development](/categories/api)

flerex/spain-gas
================

A PHP client for the Geoportal Gasolineras API

1.5(5y ago)663[1 issues](https://github.com/Flerex/spain-gas/issues)MITPHPPHP ^7.4||^8.0

Since Jan 25Pushed 5y ago1 watchersCompare

[ Source](https://github.com/Flerex/spain-gas)[ Packagist](https://packagist.org/packages/flerex/spain-gas)[ RSS](/packages/flerex-spain-gas/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (6)Dependencies (3)Versions (8)Used By (0)

Spain Gas
=========

[](#spain-gas)

[![Header](https://github.com/Flerex/spain-gas/raw/main/repo/header.png?raw=true)](https://github.com/Flerex/spain-gas/blob/main/repo/header.png?raw=true)[![Packagist Version](https://camo.githubusercontent.com/bd8a676ac6cceaa91d2f01f7755251e677410392dcf4857043b06a5e7e21d876/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f666c657265782f737061696e2d6761733f6c6162656c3d5061636b6167697374)](https://packagist.org/packages/flerex/spain-gas)[![Total Downloads](https://camo.githubusercontent.com/007194e9f6e53260670be23dde9bb4f1da0364d91081e3ae51ef25ffe4af6f24/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f666c657265782f737061696e2d6761733f6c6162656c3d446f776e6c6f616473)](https://packagist.org/packages/flerex/spain-gas)

Spain Gas is a PHP client that act as a wrapper around Spain's Geoportal Gasolineras API. It has the following main features:

- Obtain **data about all gas stations** in Spain: addresses, geolocation, provided services, schedules and much more!
- Exact **prices of fuel** for every gas station in the country, updated multiple times every day.
- Beautifully designed interface using design patterns like the builder pattern.
- Statically typed with the latest PHP typing features.
- Properly tested with coverage higher than 80%.

Requirements
------------

[](#requirements)

- You need `composer` to be installed, either globally or locally in your project.
- Compatible with **PHP 7.4 or higher**.
- PHP's extensions needed: `ext-json` and `ext-simplexml`.

Installation
------------

[](#installation)

To install this package be sure to have `composer` installed and run the following command in your project's directory:

```
composer require flerex/spain-gas

```

Usage
-----

[](#usage)

All the API's endpoints are available by using the GasApi class. Currently, there are only two endpoints for the API:

- **`gasStations`**: This is the most useful endpoint. With it, you can find gas stations by different filters such as province or availability.
- **`towns`**: Returns a list of `Town` objects. Useful to obtain the ID of a specific town to use as filter in other endpoints.
- **`locateGasStations`**: This endpoint provides the geographical location of gas stations. The only difference with the previous endpoint is that provides a ranking of the gas station according to the price of the fuel (if specified as a filter).

**NOTE:** All the aforementioned endpoints will provide the price of the fuel if specified by using the query filter `fuel`. Otherwise, it will always return `null`.

Every endpoint returns an instance of a Builder class, which provides methods to filter the request to be made. Once you selected your filtering parameters, a call to method `get` is required to actually run the request and retrieve the data.

In case you need more information about what filters are available check the Documentation.

Endpoints
---------

[](#endpoints)

Here is a list of all available endpoints, and the differences in the data retrieved.

EndpointDocumentationRankingPricesGeographical LocationStation InformationTown IDgasStations[Wiki](https://github.com/Flerex/spain-gas/wiki/Gas-Stations-endpoint)✖️✔️ \*✔️✔️✖️locateGasStations[Wiki](https://github.com/Flerex/spain-gas/wiki/Locate-Gas-Stations-endpoint)✔️ \*✔️ \*✔️✖️✖️towns[Wiki](https://github.com/Flerex/spain-gas/wiki/Towns-endpoint)✖️✖️✖️✖️✔️\* Only returned when filtering by fuel.

Example
-------

[](#example)

### Obtain Stations by Fuel

[](#obtain-stations-by-fuel)

Here is an example where we are retrieving all CNG gas stations in Spain:

```
use Flerex\SpainGas\Enums\Fuel;
use Flerex\SpainGas\GasApi;

$stations = GasApi::gasStations()
    ->fuel(Fuel::CNG())
    ->get();
```

### Get specific town ID

[](#get-specific-town-id)

Let us suppose we needed to obtain all gas stations in A Coruña (city). To be able to filter by town in the `gasStations` endpoint, we will first need to retrieve the ID of the town.

```
use Flerex\SpainGas\Dtos\Town;
use Flerex\SpainGas\Enums\Province;
use Flerex\SpainGas\GasApi;

$towns = GasApi::towns()
    ->province(Province::A_CORUNHA())
    ->get();

$townId = array_filter($towns, fn(Town $town) => stripos($town->name, 'Coruña') !== false)[0];

// Everything up to this point could be done once and then be replaced with the obtained ID to avoid unnecessary API calls.

$stations = GasApi::gasStations()
    ->town($townId)
    ->get();
```

### Get the price ranking

[](#get-the-price-ranking)

Price rankings are used to categorize the price of some fuel in a gas station comparing it to their competitors. The algorithm used by the API is unknown.

Unfortunately, rankings are only available in the `locateGasStations` endpoints.

In the following example we are going to retrieve the cheapest self-service gas stations.

```
use Flerex\SpainGas\Dtos\GasStationLocation;
use Flerex\SpainGas\Enums\Rank;
use Flerex\SpainGas\Enums\Fuel;
use Flerex\SpainGas\Enums\ServiceType;
use Flerex\SpainGas\GasApi;

$stations = GasApi::locateGasStations()
    ->serviceType(ServiceType::SELF_SERVICE())
    ->fuel(Fuel::DIESEL_A())
    ->get();

$cheapest = array_filter($stations, fn(GasStationLocation $station) => $station->rank->equals(Rank::CHEAP()));
```

**NOTE:** We need to specify a fuel so that rankings are provided in return.

Changelog
---------

[](#changelog)

Changelog can be found in [releases](https://github.com/flerex/spain-gas/releases).

Copyright and License
---------------------

[](#copyright-and-license)

[Spain Gas](https://github.com/flerex/spain-gas) was written by [Flerex](https://flerex.dev) and is released under the [MIT License](LICENSE).

© Flerex 2020

###  Health Score

28

—

LowBetter than 52% of packages

Maintenance17

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~26 days

Total

6

Last Release

1853d ago

PHP version history (2 changes)1.0PHP ^7.4

1.4PHP ^7.4||^8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3910120?v=4)[Flerex](/maintainers/Flerex)[@Flerex](https://github.com/Flerex)

---

Top Contributors

[![Flerex](https://avatars.githubusercontent.com/u/3910120?v=4)](https://github.com/Flerex "Flerex (45 commits)")

---

Tags

apigasgasolinegasoline-pricesgasolinerasgeoportalphppreciosspainclientgeoportalgasolineras

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/flerex-spain-gas/health.svg)

```
[![Health](https://phpackages.com/badges/flerex-spain-gas/health.svg)](https://phpackages.com/packages/flerex-spain-gas)
```

###  Alternatives

[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k9.5M87](/packages/openai-php-laravel)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3741.3M46](/packages/tencentcloud-tencentcloud-sdk-php)[netflie/whatsapp-cloud-api

The first PHP SDK to send and receive messages using a cloud-hosted version of the WhatsApp Business Platform

668535.6k5](/packages/netflie-whatsapp-cloud-api)[resend/resend-php

Resend PHP library.

617.2M42](/packages/resend-resend-php)[flowwow/cloudpayments-php-client

cloudpayments api client

21101.2k](/packages/flowwow-cloudpayments-php-client)[files.com/files-php-sdk

Files.com PHP SDK

2481.1k](/packages/filescom-files-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)