Skip to content

Calculations Export API

The Calculations Export API provides an asynchronous way to generate and download calculation results as CSV files. This two-endpoint system is designed for municipalities that need to integrate HouMeerOver calculation data into their own systems, reporting workflows, or financial processes.

Purpose

The export endpoint serves key municipal integration needs:

  • Bulk data download: Retrieve all calculation results in a single CSV file
  • Financial system integration: Export data for payment processing and subsidy disbursement
  • Reporting and analysis: Download structured data for municipal reporting requirements
  • Data archival: Create local backups of calculation results for record-keeping
  • Third-party system integration: Feed calculation data into existing municipal software

Key Features

  • Asynchronous processing: Exports are handled in the background using Celery tasks
  • Progress tracking: Monitor export status through the status API
  • Municipality-scoped data: Automatically filters to your municipality's calculations
  • Ready-to-use format: CSV output optimized for spreadsheet and database import
  • Filtered exports: Apply date ranges and batch filters to limit results
  • Calculation history control: Choose between latest calculations only or full calculation history
  • Completion status filtering: Include or exclude incomplete calculations without subsidy amounts
  • Consistent format: Standardized column structure matching the API response format
  • File storage: Generated CSV files are stored securely and accessible via direct URL
  • Short-lived URLs: Download URLs expire after 30 seconds for security

Authentication Required

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

Municipality Scoping

Important: Export data is automatically scoped to your municipality. The API only exports calculations that belong to the municipality associated with your OAuth2 application. You cannot export calculation data from other municipalities.

Basic Usage

The export process follows a two-step workflow:

1. Create Export Request

Endpoint: POST /api/v1/calculations/export

Start the export process by submitting a request with optional filters. This endpoint returns a uuid and status that you'll use to track the export progress and retrieve the results.

Example Request:

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

Response:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}

2. Check Status and Download Results

Endpoint: GET /api/v1/calculations/export/{uuid}

Monitor the progress and retrieve results using the UUID returned from the create request. The status will progress from pending to completed or failed.

Example Request:

curl -X GET "https://api.houmeerover.nl/api/v1/calculations/export/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (In Progress):

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "csv": null
}

Response (Completed):

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000", 
  "status": "completed",
  "csv": "https://storage.houmeerover.nl/exports/calculations_export_550e8400-e29b-41d4-a716-446655440000.csv"
}

Once the status shows completed, the csv field will contain a direct download URL for the generated CSV file.

Important: The download URL expires after 30 seconds for security reasons. Download the file immediately after receiving the completed status response.

Filtering and Options

The export endpoint supports filtering options to control which calculations are included in the export. Common filters include date ranges (created_after, created_before), batch filters (batch_id), and options to control calculation history (only_last_calculation) and completion status (only_completed_calculations).

Example with multiple filters:

curl -X POST "https://api.houmeerover.nl/api/v1/calculations/export?only_last_calculation=true&created_after=2025-01-01T00:00:00Z&batch_id=123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

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

CSV Format

The exported CSV file contains calculation data in a structured format optimized for spreadsheet and database import. The exact column structure and data format details are available in the Interactive API Documentation.

Example CSV structure:

subsidy_amount,postal_code,house_number,house_letter,house_number_addition,municipality,calculated_at,created_at,modified_at
250.00,1234AB,123,A,,ABC,2025-10-16T14:30:00Z,2025-10-16T14:30:00Z,2025-10-16T14:30:00Z
180.50,5678CD,456,,,DEF,2025-10-16T14:31:15Z,2025-10-16T14:31:15Z,2025-10-16T14:31:15Z

Technical Documentation

For complete technical documentation including:

  • All available request parameters and filtering options
  • Complete response schemas and status codes
  • Error codes and handling strategies
  • Rate limiting and usage guidelines
  • Authentication requirements and scopes

Visit the interactive Swagger documentation: HouMeerOver API Documentation

The Swagger interface provides up-to-date technical specifications and allows you to:

  • Test the complete export workflow with your authentication
  • View detailed parameter descriptions and validation rules
  • See live examples and test requests directly
  • Explore the exact response formats and error codes
  • Download CSV files directly in your browser

Ready to explore other endpoints? Return to the API Endpoints Overview or learn about real-time updates with Webhooks.