Gas Safe Register APIgassaferegister.co.uk ↗

"""
Gas Safe Register API Client

This module provides a Python client for searching Gas Safe registered businesses
and engineers in the UK.

Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional


class ParseClient:
    """Client for interacting with the Gas Safe Register Parse API."""
    
    def __init__(self, api_key: Optional[str] = None):
        """Initialize the Parse API client.
        
        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "82a3f423-3c12-4a96-adf0-1f9c67dc1389"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")
    
    def _call(self, endpoint: str, method: str = "POST", **params) -> dict:
        """Make an API call to the Parse endpoint.
        
        Args:
            endpoint: The endpoint name to call
            method: HTTP method (GET or POST)
            **params: Query parameters or request body
            
        Returns:
            Response JSON as dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }
        
        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        else:
            response = requests.post(url, headers=headers, json=params)
        
        response.raise_for_status()
        return response.json()
    
    def search_businesses(
        self,
        location: str,
        service_type: str = "Domestic",
        page: int = 1,
        include_engineers: str = "true"
    ) -> dict:
        """Search for Gas Safe registered businesses by location.
        
        Args:
            location: City name or UK postcode
            service_type: Type of gas service ('Domestic' or 'Commercial')
            page: Page number (1-indexed, 10 results per page)
            include_engineers: Whether to fetch engineer details ('true' or 'false')
            
        Returns:
            Dictionary containing business results with optional engineer details
        """
        return self._call(
            "search_businesses",
            method="GET",
            location=location,
            service_type=service_type,
            page=page,
            include_engineers=include_engineers
        )
    
    def search_businesses_basic(
        self,
        location: str,
        service_type: str = "Domestic",
        page: int = 1
    ) -> dict:
        """Search for Gas Safe registered businesses by location (without engineer details).
        
        Args:
            location: City name or UK postcode
            service_type: Type of gas service ('Domestic' or 'Commercial')
            page: Page number (1-indexed, 10 results per page)
            
        Returns:
            Dictionary containing business results without engineer details
        """
        return self._call(
            "search_businesses_basic",
            method="GET",
            location=location,
            service_type=service_type,
            page=page
        )
    
    def get_business_engineers(self, registration_number: str) -> dict:
        """Get engineers for a specific Gas Safe registered business.
        
        Args:
            registration_number: Gas Safe registration number (e.g. '167722')
            
        Returns:
            Dictionary containing business details and engineers
        """
        return self._call(
            "get_business_engineers",
            method="GET",
            registration_number=registration_number
        )


def main():
    """Practical workflow: Search for businesses, then get detailed engineer info for top results."""
    
    # Initialize the client
    client = ParseClient()
    
    location = "London"
    service_type = "Domestic"
    
    # Step 1: Search for Gas Safe businesses in a location
    print("=" * 70)
    print(f"Searching for Gas Safe registered {service_type} businesses in {location}...")
    print("=" * 70)
    
    search_results = client.search_businesses_basic(
        location=location,
        service_type=service_type,
        page=1
    )
    
    total_results = search_results.get("total_results", 0)
    results_on_page = search_results.get("results_on_page", 0)
    businesses = search_results.get("businesses", [])
    
    print(f"\nFound {total_results} businesses total")
    print(f"Displaying {results_on_page} results on page 1\n")
    
    # Step 2: Display summary of first few businesses
    print("-" * 70)
    print("BUSINESSES FOUND:")
    print("-" * 70)
    
    for idx, business in enumerate(businesses[:5], 1):
        print(f"\n{idx}. {business['business_name']}")
        print(f"   Reg #: {business['registration_number']}")
        print(f"   Address: {business['address']['full_address']}")
        print(f"   Phone: {business['telephone']}")
        print(f"   Email: {business['email']}")
    
    # Step 3: Get detailed engineer information for each of the top 3 businesses
    print("\n" + "=" * 70)
    print("FETCHING DETAILED ENGINEER INFORMATION...")
    print("=" * 70)
    
    for idx, business in enumerate(businesses[:3], 1):
        registration_number = business["registration_number"]
        business_name = business["business_name"]
        
        print(f"\n{idx}. {business_name} (Reg #{registration_number})")
        print("-" * 70)
        
        try:
            engineer_data = client.get_business_engineers(registration_number)
            
            business_info = engineer_data.get("business", {})
            engineers = engineer_data.get("engineers", [])
            
            print(f"   Location: {business_info['address']['full_address']}")
            print(f"   Phone: {business_info['telephone']}")
            print(f"   Email: {business_info['email']}")
            print(f"   Out of hours available: {business_info.get('out_of_hours_available', False)}")
            
            print(f"\n   ENGINEERS ({len(engineers)} registered):")
            
            if engineers:
                for eng_idx, engineer in enumerate(engineers, 1):
                    print(f"      {eng_idx}. {engineer['name']}")
                    print(f"         Services: {', '.join(engineer['services'])}")
                    print(f"         Status: {engineer['status']}")
                    if engineer.get('telephone'):
                        print(f"         Phone: {engineer['telephone']}")
            else:
                print("      No engineers found for this business")
                
        except Exception as e:
            print(f"   Error fetching engineers: {e}")
    
    # Step 4: Search for Commercial services to show different service types
    print("\n" + "=" * 70)
    print(f"Searching for {location} - COMMERCIAL services...")
    print("=" * 70)
    
    commercial_results = client.search_businesses_basic(
        location=location,
        service_type="Commercial",
        page=1
    )
    
    commercial_total = commercial_results.get("total_results", 0)
    commercial_businesses = commercial_results.get("businesses", [])
    
    print(f"\nFound {commercial_total} commercial service providers")
    
    if commercial_businesses:
        print(f"Showing {len(commercial_businesses[:3])} results:\n")
        
        for idx, business in enumerate(commercial_businesses[:3], 1):
            print(f"{idx}. {business['business_name']}")
            print(f"   Reg #: {business['registration_number']}")
            print(f"   Address: {business['address']['full_address']}")
            print(f"   Phone: {business['telephone']}\n")
    else:
        print("No commercial service providers found in this location.\n")
    
    # Summary statistics
    print("=" * 70)
    print("SEARCH SUMMARY")
    print("=" * 70)
    print(f"Location: {location}")
    print(f"Domestic businesses found: {total_results}")
    print(f"Commercial businesses found: {commercial_total}")
    print(f"Total: {total_results + commercial_total}")
    print("\nUse registration numbers to get detailed engineer information.")


if __name__ == "__main__":
    main()