Skip to content

Calculations API

The Calculations API provides access to completed energy subsidy calculations for your municipality. This endpoint allows you to retrieve calculation results, address information, and resident login codes in a paginated format with flexible filtering options.

Purpose

The Calculations endpoint serves several key purposes for municipal integrations:

  • Retrieve calculation results: Access subsidy amounts, addresses, and associated metadata
  • Integration with municipal systems: Sync calculation data with local databases, payment systems, or reporting tools
  • Data filtering and search: Find specific calculations by date, subsidy amount, or other criteria
  • Paginated access: Handle large datasets efficiently through pagination
  • Real-time updates: Access the most current calculation data as it becomes available

Key Features

  • Municipality-scoped data: Returns only calculations for your municipality
  • Flexible filtering: Filter by creation date, modification date, and subsidy amount ranges
  • Calculation history control: Choose between latest calculations only or full calculation history
  • Completion status filtering: Include or exclude incomplete calculations without subsidy amounts
  • Pagination support: Efficiently handle large datasets with configurable page sizes
  • Standard REST format: Consistent JSON responses with predictable structure
  • OAuth2 authentication: Secure access with calculations:read scope

Basic Usage

Retrieve Calculations

Endpoint: GET /api/v1/calculations

Retrieve a paginated list of calculation results for your municipality. The API supports filtering by dates, batch information, and pagination controls.

Example Request:

curl -X GET "https://api.houmeerover.nl/api/v1/calculations?created_after=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "items": [
    {
      "subsidy_amount": "250.00",
      "calculated_at": "2025-10-16T14:30:00Z",
      "created_at": "2025-10-16T14:30:00Z", 
      "modified_at": "2025-10-16T14:30:00Z",
      "address": {
        "postal_code": "1234AB",
        "house_number": 123,
        "house_letter": "A",
        "house_number_addition": "",
        "municipality": "ABC"
      }
    }
  ],
  "count": 1,
  "next": null,
  "previous": null
}

Filtering and Pagination

The API supports comprehensive filtering options including:

  • Date filtering: Filter by creation, modification, or calculation dates
  • Batch filtering: Filter by specific batch ID or name
  • Calculation history: Control whether to return only the latest calculation per address (only_last_calculation=true, default) or all calculation history (only_last_calculation=false)
  • Completion status: Control whether to return only completed calculations with subsidy amounts (only_completed_calculations=true, default) or include incomplete calculations (only_completed_calculations=false)
  • Pagination: Navigate through large result sets

Important Query Parameters

  • only_last_calculation (boolean, default: true): When true, returns only the most recent calculation per batch item. When false, returns all calculations including historical recalculations.
  • only_completed_calculations (boolean, default: true): When true, returns only calculations that have been completed and have a subsidy amount. When false, includes calculations that are still in progress or failed.

For complete details on all available parameters and their formats, see the Interactive API Documentation.

Authentication Required

This endpoint requires OAuth2 authentication with the calculations:read scope. See OAuth2 Authentication for setup instructions.

Municipality Scoping

Important: All calculation data returned by this API is automatically scoped to your municipality. The API only returns calculations that belong to the municipality associated with your OAuth2 application. You cannot access calculation data from other municipalities.

Technical Documentation

For complete technical documentation including:

  • Request/response schemas
  • All available parameters and filters
  • Error codes and responses
  • Example requests and responses
  • Rate limiting details

Visit the interactive Swagger documentation: HouMeerOver API Documentation

The Swagger interface allows you to:

  • Test API calls directly in your browser
  • View detailed parameter descriptions
  • See live examples with your authentication
  • Explore all available endpoints and methods

Ready to explore other endpoints? Return to the API Endpoints Overview or check out Calculations Export for bulk data operations.