Fuel Price | API

Best Practices

This guide covers best practices for integrating the FuelPrice API into your application. Learn how to cache data effectively, minimize API calls, and build a responsive user experience.

The most important principle: Store API data in your database. Never hit the API directly for every user request. This improves performance, reduces costs, and provides a better user experience.

Why Cache Locally?

Always store FuelPrice API data in your own database and serve from there. The API should be used to refresh your local data, not to serve every user request.

Benefits:

  • Performance - Database queries are 10-100x faster than API calls
  • Reliability - Your app works even if the API is temporarily unavailable
  • Cost - Reduce API usage and stay within rate limits
  • User Experience - Instant responses instead of waiting for external requests

Different data types have different update frequencies. Match your cache duration to the data's change rate:

  • Name
    Fuel Prices & History
    Description

    6-24 hours - In Australia, fuel prices typically change once daily. Update once or twice per day to stay current.

  • Name
    Station Information
    Description

    7 days - Station details (name, address, location) change infrequently. Weekly updates are sufficient.

  • Name
    Suburbs & Cities
    Description

    7 days - Geographic data is mostly static. Update weekly.

Implementation Patterns

Pattern 1: Check Database First

Use this pattern when you need on-demand data fetching:

  1. User requests data from your application
  2. Check your database for existing data with a timestamp
  3. If data exists and is fresh (timestamp < 12 hours old for prices), return it immediately
  4. If data is stale or missing, fetch from the FuelPrice API
  5. Store the API response in your database with current timestamp
  6. Return the data to the user

This pattern ensures users get fast responses from cache when possible, and fresh data when needed.

Pattern 2: Background Refresh (Recommended)

Use this pattern for the best user experience - users never wait for API calls:

  1. Set up a scheduled job (cron, task scheduler) to run 1-2 times daily (e.g., 6am and 6pm)
  2. Job fetches data from FuelPrice API for all resources you need
  3. Job updates your database with fresh data and timestamps
  4. All user requests read directly from your database only
  5. Users get instant responses - they never wait for API calls

Since Australian fuel prices change once daily, refreshing twice per day ensures your data is always current.

What to Store in Your Database

When caching API data, store these key pieces of information:

  • Resource data - The full JSON response or extracted fields you need
  • Timestamp - When the data was last fetched from the API
  • Resource identifier - The ID of the suburb, station, city, etc.
  • Expiry time (optional) - Calculated time when data becomes stale

Example structure:

  • id - Unique identifier
  • resource_type - 'suburb', 'station', 'city', etc.
  • resource_id - The ID from the API
  • data - JSON or structured fields
  • fetched_at - Timestamp when data was retrieved
  • expires_at - Calculated expiry time

Optimization Tips

Use Pagination

Don't fetch more data than you need. Use limit and offset parameters:

  • ✅ Fetch 50 stations per page with ?limit=50&offset=0

Handle Errors Gracefully

Implement proper error handling:

  1. Wrap API calls in try/catch blocks
  2. If API fails, fall back to cached data (even if slightly stale)
  3. Log errors for monitoring and debugging
  4. Never expose raw API errors to end users

Monitor Your Usage

Track your API calls to identify optimization opportunities:

  • Log each API request with timestamp, endpoint, and response time
  • Review logs weekly to find patterns or excessive usage
  • Set up alerts if API usage exceeds expected thresholds
  • Monitor error rates to catch issues early

Consider Stale-While-Revalidate

For advanced implementations:

  1. Check cache for data
  2. If data exists but is stale, return it immediately to the user
  3. Trigger background refresh to update the cache for next request
  4. Users get instant responses with data that's "good enough"

Key Takeaways

Remember these core principles:

  1. ✅ Always cache in your database - Never hit the API for every user request
  2. ✅ Match cache duration to data type - Fuel prices change daily, locations rarely change
  3. ✅ Use background jobs when possible - Refresh data proactively, not reactively
  4. ✅ Handle errors gracefully - Fall back to cached data when API fails
  5. ✅ Monitor your usage - Track API calls to optimize performance and costs

Following these practices will result in a faster, more reliable application that provides a better experience for your users while minimizing API usage and costs.

Learn about rate limits