5. API Services

5.1. Overview

The application uses a clean, reusable API service architecture for fetching hospital data from New Zealand’s government data catalogue (catalogue.data.govt.nz). This service completely replaces CSV-based data loading with real-time API calls.

Data License: All hospital data is provided under open data principles as defined by the Open Definition 2.1, allowing free access, use, modification, and sharing while preserving provenance and openness.

5.2. Service Architecture

Service Layer (services/hospitalApi.js):

  • Single Responsibility: Handles all hospital data API interactions

  • Clean Interface: Simple methods for fetching different hospital types

  • Error Handling: Robust error handling with automatic retries

  • Rate Limiting: Built-in delays to respect API limits

  • JSONP Support: Cross-origin requests without CORS issues

5.3. Resource Configuration

API Endpoints:

  • Public Hospitals: dccdddd8-708d-4798-adaf-609c31f93414

  • NGO Hospitals: 1c3bc030-57cd-4a4e-ba22-4496f4ded0b1

  • Fertility Clinics: ef9242b0-cac1-4d26-82a1-6273d41beaa2

Base URL: https://catalogue.data.govt.nz/api/3/action/datastore_search

5.4. Key Features

  • Complete Data Fetching: Automatically fetches ALL records using pagination (no 5-record limit)

  • Data Transformation: Standardizes API responses to consistent format

  • Performance: Parallel requests for multiple hospital types

  • Type Safety: JSDoc annotations for better IDE support

  • Clean Code: Follows SOLID principles and DRY methodology

5.5. Usage Example

import hospitalApiService from '~/services/hospitalApi.js';

// Fetch all public hospitals
const publicHospitals = await hospitalApiService.fetchAllRecords('publicHospitals');

// Fetch all hospital types in parallel
const [publicHospitals, ngoHospitals, fertilityClinic] = await Promise.all([
  hospitalApiService.fetchAllRecords('publicHospitals'),
  hospitalApiService.fetchAllRecords('ngoHospitals'),
  hospitalApiService.fetchAllRecords('fertilityClinic')
]);

5.6. Data Structure

Each hospital record contains standardized fields:

{
  id: string,           // Unique identifier
  name: string,         // Hospital name
  addr1: string,        // Address line 1
  addr2: string,        // Address line 2
  suburb: string,       // Suburb
  city: string,         // City/Town
  postcode: string,     // Postal code
  website: string,      // Website URL
  type: string,         // Hospital type
  serviceTypes: string, // Available services
  beds: string,         // Number of beds
  region: string        // Region (same as city)
}

5.7. Configuration Management

Resource IDs can be updated dynamically:

hospitalApiService.updateResourceId('publicHospitals', 'new-resource-id');

5.8. Technical Benefits

  1. Real-time Data: Always fetches the latest hospital information

  2. Complete Coverage: Gets ALL records, not just 5 samples

  3. Performance: Parallel API calls reduce loading time

  4. Maintainability: Single service for all hospital data

  5. Scalability: Easy to add new hospital types

  6. Clean Code: Follows SOLID principles and DRY methodology

  7. No Dependencies: Pure JavaScript implementation without jQuery

5.9. Implementation Details

JSONP Implementation:

  • Uses dynamic script injection for cross-origin requests

  • Automatic callback cleanup to prevent memory leaks

  • Built-in timeout handling (30 seconds)

Pagination Strategy:

  • Automatic pagination to fetch complete datasets

  • Configurable page size (default: 100 records)

  • Built-in rate limiting to respect API constraints

Data Transformation Pipeline:

  • Standardized field mapping across different hospital types

  • Flexible field name resolution for API variations

  • Consistent data structure output

Error Handling:

  • Comprehensive error catching and reporting

  • Meaningful error messages for debugging

  • Graceful degradation on network failures

5.10. Integration

The API service integrates seamlessly with Vue.js components:

export default {
  data() {
    return {
      hospitals: [],
      loading: false,
      error: null,
    };
  },
  async mounted() {
    await this.loadHospitals();
  },
  methods: {
    async loadHospitals() {
      this.loading = true;
      try {
        const allHospitals = await Promise.all([
          hospitalApiService.fetchAllRecords('publicHospitals'),
          hospitalApiService.fetchAllRecords('ngoHospitals'),
          hospitalApiService.fetchAllRecords('fertilityClinic')
        ]);
        this.hospitals = allHospitals.flat();
      } catch (error) {
        this.error = 'Failed to load hospital data';
      } finally {
        this.loading = false;
      }
    }
  }
};

This architecture ensures clean separation of concerns, maintainable code, and optimal performance for real-time data fetching.

5.11. Data Attribution and Licensing

Source: NZ Government Open Data - Certified Health Care Providers

License: Open Definition 2.1 - Free to access, use, modify, and share

For implementation examples, see the 04_pregnancy_app/00_pages:Hospital Data Integration documentation.