PetrolSpy APIpetrolspy.com.au ↗
Access real-time Australian fuel prices via the PetrolSpy API. Search stations by bounding box, compare prices by fuel type, and get full station details.
What is the PetrolSpy API?
The PetrolSpy API provides real-time fuel price data from petrol stations across Australia through 3 endpoints. Use search_stations to retrieve all stations within a geographic bounding box along with their prices for every available fuel type, get_cheapest_prices to rank stations by lowest price for a specific fuel type, or get_station_details to pull complete pricing, trading hours, and amenity data for a single station by its PetrolSpy ID.
curl -X GET 'https://api.parse.bot/scraper/7bf5e451-0619-4e7d-85d9-3c57a1ce5738/search_stations?limit=10&ne_lat=-33.76&ne_lng=151.07&sw_lat=-33.86&sw_lng=150.94&fuel_type=E10' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace petrolspy-com-au-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: PetrolSpy SDK — find cheapest fuel in Australian areas."""
from parse_apis.petrolspy_com_au_api import PetrolSpy, FuelType, StationNotFound
client = PetrolSpy()
# Search stations in the Parramatta/Western Sydney area, sorted by E10 price
for station in client.stations.search(
ne_lat="-33.76", ne_lng="151.07", sw_lat="-33.86", sw_lng="150.94",
fuel_type=FuelType.E10, limit=3
):
print(station.name, station.brand, station.fuel_price)
for fuel, fp in station.prices.items():
print(f" {fuel}: {fp.amount} cents/L (reported by {fp.reported_by})")
# Find cheapest U91 prices in the same area
cheapest = client.stations.cheapest(
ne_lat="-33.76", ne_lng="151.07", sw_lat="-33.86", sw_lng="150.94",
fuel_type=FuelType.U91, limit=1
).first()
# Drill into station details from cheapest price result
if cheapest:
try:
detail = cheapest.details(
ne_lat="-33.76", ne_lng="151.07", sw_lat="-33.86", sw_lng="150.94"
)
print(detail.name, detail.address, detail.suburb, detail.open_24h)
except StationNotFound as exc:
print(f"Station no longer available: {exc}")
print("exercised: stations.search / stations.cheapest / cheapest.details / FuelPrice access")
Search for fuel stations within a geographic bounding box. Returns stations with all available fuel prices, sorted by the requested fuel type price (cheapest first). Stations without the requested fuel type appear at the end.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of stations to return. |
| ne_latrequired | string | Northeast corner latitude of the bounding box (decimal degrees, e.g. -33.76). |
| ne_lngrequired | string | Northeast corner longitude of the bounding box (decimal degrees, e.g. 151.07). |
| sw_latrequired | string | Southwest corner latitude of the bounding box (decimal degrees, e.g. -33.86). |
| sw_lngrequired | string | Southwest corner longitude of the bounding box (decimal degrees, e.g. 150.94). |
| fuel_type | string | Fuel type to sort stations by price. |
{
"type": "object",
"fields": {
"stations": "array of station objects with id, name, brand, address, suburb, state, post_code, country, latitude, longitude, phone, open_24h, has_restrooms, is_adblue_available, fuel_price, and prices",
"fuel_type": "string",
"total_stations": "integer"
},
"sample": {
"data": {
"stations": [
{
"id": "523274ca036466fee4985694",
"name": "Speedway Petroleum",
"brand": "SPEEDWAY",
"phone": "0297251816",
"state": "NSW",
"prices": {
"E10": {
"amount": 157.5,
"updated": 1783693866275,
"reported_by": "NSW Gov Open Data Fuel API"
},
"DIESEL": {
"amount": 177.5,
"updated": 1783693866275,
"reported_by": "NSW Gov Open Data Fuel API"
}
},
"suburb": "Smithfield",
"address": "26-28 Cumberland Highway Cnr Victoria St",
"country": "AU",
"latitude": -33.851585,
"open_24h": false,
"longitude": 150.942796,
"post_code": "2164",
"fuel_price": 157.5,
"has_restrooms": false,
"is_adblue_available": true
}
],
"fuel_type": "E10",
"total_stations": 5
},
"status": "success"
}
}About the PetrolSpy API
What the API Returns
All three endpoints work with a geographic bounding box defined by four required parameters — ne_lat, ne_lng, sw_lat, and sw_lng — expressed as decimal-degree coordinates. search_stations returns an array of station objects, each carrying fields including id, name, brand, address, suburb, state, post_code, latitude, longitude, phone, open_24h, and all available fuel prices. Results are sorted by price for the requested fuel_type; stations that do not carry that fuel type appear at the end of the list.
Cheapest Prices Endpoint
get_cheapest_prices filters to only those stations that stock the specified fuel_type and returns them sorted ascending by price. Each record in cheapest_prices includes station_id, station_name, brand, address, suburb, state, post_code, latitude, longitude, price, and an updated timestamp indicating how fresh the reading is. An optional limit parameter controls how many results are returned, making it straightforward to retrieve, say, the five cheapest stations in a given area.
Station Detail Endpoint
get_station_details accepts a station_id (alphanumeric, e.g. 523274ca036466fee4985694) obtainable from either of the other endpoints, plus the bounding box that contains the station. It returns the full station record: all fuel types mapped to price objects that include amount, updated, and reported_by, plus trading hours and amenities. This is the only endpoint that exposes the reported_by field, showing which community member last submitted a price update.
The PetrolSpy API is a managed, monitored endpoint for petrolspy.com.au — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when petrolspy.com.au changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official petrolspy.com.au API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a fuel price comparison app that maps the cheapest stations for E10, 91, 95, 98, or diesel within a user's visible map area.
- Alert users when a fuel price in their suburb drops below a set threshold by polling
get_cheapest_priceson a schedule. - Populate a fleet management dashboard with current diesel prices across multiple Australian states using bounding-box queries.
- Display station amenities and full trading hours in a route-planning tool using
get_station_detailsfor each stop. - Analyse regional fuel price trends by recording
priceandupdatedtimestamps fromsearch_stationsqueries over time. - Show drivers the nearest 24-hour petrol stations with the
open_24hfield returned bysearch_stations.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does PetrolSpy have an official developer API?+
What does the `reported_by` field in `get_station_details` tell me?+
reported_by appears inside each fuel-type price object and identifies the community contributor who last submitted that price reading. It is only available from get_station_details, not from search_stations or get_cheapest_prices.How current are the fuel prices returned?+
updated timestamp (returned as the updated field in get_cheapest_prices and as updated inside the prices object in get_station_details). PetrolSpy relies on community-reported prices, so freshness varies by station and location — popular urban stations tend to have more recent updates than rural ones.