bolster.data_sources.nisra.tourism

NISRA Tourism Statistics Data Sources.

This module provides access to Northern Ireland tourism data including:

  • Occupancy Surveys: Hotel and SSA (B&B/guest house) occupancy rates

  • Visitor Statistics: Quarterly trips, nights spent, and expenditure by market

  • Air Passenger Flow: Airport throughput data (coming soon)

All data is sourced from NISRA (Northern Ireland Statistics and Research Agency) and published under the Open Government Licence.

Example

>>> from bolster.data_sources.nisra.tourism import occupancy
>>> df = occupancy.get_latest_hotel_occupancy()
>>> 'room_occupancy' in df.columns
True
>>> df_combined = occupancy.get_combined_occupancy()
>>> comparison = occupancy.compare_accommodation_types(df_combined)
>>> 'difference' in comparison.columns
True
>>> from bolster.data_sources.nisra.tourism import visitor_statistics
>>> vs = visitor_statistics.get_latest_visitor_statistics()
>>> 'market' in vs.columns
True

See individual module docstrings for detailed documentation.

Submodules

Functions

compare_accommodation_types(df[, metric])

Compare occupancy between hotel and SSA by year.

get_combined_occupancy([force_refresh])

Get combined hotel and SSA occupancy data with accommodation type column.

get_latest_hotel_occupancy([force_refresh])

Get the latest monthly hotel occupancy rates data.

get_latest_hotel_occupancy_publication_url()

Scrape NISRA occupancy surveys page to find the latest hotel occupancy file.

get_latest_rooms_beds_sold([force_refresh])

Get the latest monthly rooms and beds sold data.

get_latest_ssa_occupancy([force_refresh])

Get the latest monthly SSA occupancy rates data.

get_latest_ssa_occupancy_publication_url()

Scrape NISRA occupancy surveys page to find the latest SSA file.

get_latest_ssa_rooms_beds_sold([force_refresh])

Get the latest monthly SSA rooms and beds sold data.

get_occupancy_by_year(df, year)

Filter occupancy data for a specific year.

get_occupancy_summary_by_year(df)

Calculate annual occupancy averages and statistics.

get_seasonal_patterns(df)

Calculate average occupancy by month across all years.

Package Contents

bolster.data_sources.nisra.tourism.compare_accommodation_types(df, metric='room_occupancy')[source]

Compare occupancy between hotel and SSA by year.

Parameters:

  • df (pandas.DataFrame) – DataFrame from get_combined_occupancy()

  • metric (Literal['room_occupancy', 'bed_occupancy']) – Which occupancy metric to compare

Returns:

  • year: int

  • hotel_{metric}: float

  • ssa_{metric}: float

  • difference: float (hotel - ssa)

  • ratio: float (hotel / ssa)

Return type:

DataFrame with columns

Example

>>> df = get_combined_occupancy()
>>> comparison = compare_accommodation_types(df)
>>> 'difference' in comparison.columns
True
bolster.data_sources.nisra.tourism.get_combined_occupancy(force_refresh=False)[source]

Get combined hotel and SSA occupancy data with accommodation type column.

This function fetches both hotel and SSA occupancy data and combines them into a single DataFrame with an ‘accommodation_type’ column to distinguish between the two accommodation types.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • date: datetime (first day of month)

  • year: int

  • month: str (month name)

  • room_occupancy: float (room occupancy rate, 0-1)

  • bed_occupancy: float (bed occupancy rate, 0-1)

  • accommodation_type: str (‘hotel’ or ‘ssa’)

Return type:

DataFrame with columns

Example

>>> df = get_combined_occupancy()
>>> 'accommodation_type' in df.columns
True
bolster.data_sources.nisra.tourism.get_latest_hotel_occupancy(force_refresh=False)[source]

Get the latest monthly hotel occupancy rates data.

Automatically discovers and downloads the most recent hotel occupancy data from the NISRA website.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • date: datetime (first day of month)

  • year: int

  • month: str (month name)

  • room_occupancy: float (room occupancy rate, 0-1)

  • bed_occupancy: float (bed occupancy rate, 0-1)

Return type:

DataFrame with columns

Raises:

  • NISRADataNotFoundError – If latest publication cannot be found

  • NISRAValidationError – If file structure is unexpected

Example

>>> df = get_latest_hotel_occupancy()
>>> 'room_occupancy' in df.columns
True
bolster.data_sources.nisra.tourism.get_latest_hotel_occupancy_publication_url()[source]

Scrape NISRA occupancy surveys page to find the latest hotel occupancy file.

Navigates the publication structure: 1. Scrapes mother page for latest hotel occupancy publication 2. Follows link to publication detail page 3. Finds hotel occupancy Excel file

Returns:

Tuple of (excel_file_url, publication_date)

Raises:

NISRADataNotFoundError – If publication or file not found

Return type:

tuple[str, str]

bolster.data_sources.nisra.tourism.get_latest_rooms_beds_sold(force_refresh=False)[source]

Get the latest monthly rooms and beds sold data.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • date: datetime (first day of month)

  • year: int

  • month: str (month name)

  • rooms_sold: float (number of rooms sold)

  • beds_sold: float (number of beds sold)

Return type:

DataFrame with columns

Example

>>> df = get_latest_rooms_beds_sold()
>>> 'rooms_sold' in df.columns
True
bolster.data_sources.nisra.tourism.get_latest_ssa_occupancy(force_refresh=False)[source]

Get the latest monthly SSA occupancy rates data.

SSA = Small Service Accommodation (B&Bs, guest houses, etc.)

Automatically discovers and downloads the most recent SSA occupancy data from the NISRA website.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • date: datetime (first day of month)

  • year: int

  • month: str (month name)

  • room_occupancy: float (room occupancy rate, 0-1)

  • bed_occupancy: float (bed occupancy rate, 0-1)

Return type:

DataFrame with columns

Raises:

  • NISRADataNotFoundError – If latest publication cannot be found

  • NISRAValidationError – If file structure is unexpected

Example

>>> df = get_latest_ssa_occupancy()
>>> 'room_occupancy' in df.columns
True
bolster.data_sources.nisra.tourism.get_latest_ssa_occupancy_publication_url()[source]

Scrape NISRA occupancy surveys page to find the latest SSA file.

SSA = Small Service Accommodation (B&Bs, guest houses, etc.)

Navigates the publication structure: 1. Scrapes mother page for latest SSA occupancy publication 2. Follows link to publication detail page 3. Finds SSA occupancy Excel file

Returns:

Tuple of (excel_file_url, publication_date)

Raises:

NISRADataNotFoundError – If publication or file not found

Return type:

tuple[str, str]

bolster.data_sources.nisra.tourism.get_latest_ssa_rooms_beds_sold(force_refresh=False)[source]

Get the latest monthly SSA rooms and beds sold data.

SSA = Small Service Accommodation (B&Bs, guest houses, etc.)

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • date: datetime (first day of month)

  • year: int

  • month: str (month name)

  • rooms_sold: float (number of rooms sold)

  • beds_sold: float (number of beds sold)

Return type:

DataFrame with columns

Example

>>> df = get_latest_ssa_rooms_beds_sold()
>>> 'rooms_sold' in df.columns
True
bolster.data_sources.nisra.tourism.get_occupancy_by_year(df, year)[source]

Filter occupancy data for a specific year.

Parameters:

  • df (pandas.DataFrame) – DataFrame from get_latest_hotel_occupancy()

  • year (int) – Year to filter

Returns:

Filtered DataFrame

Return type:

pandas.DataFrame

bolster.data_sources.nisra.tourism.get_occupancy_summary_by_year(df)[source]

Calculate annual occupancy averages and statistics.

Parameters:

df (pandas.DataFrame) – DataFrame from get_latest_hotel_occupancy()

Returns:

  • year: int

  • avg_room_occupancy: float

  • avg_bed_occupancy: float

  • months_reported: int

Return type:

DataFrame with columns

bolster.data_sources.nisra.tourism.get_seasonal_patterns(df)[source]

Calculate average occupancy by month across all years.

Parameters:

df (pandas.DataFrame) – DataFrame from get_latest_hotel_occupancy()

Returns:

  • month: str (month name)

  • avg_room_occupancy: float

  • avg_bed_occupancy: float

Return type:

DataFrame with columns

Example

>>> df = get_latest_hotel_occupancy()
>>> seasonal = get_seasonal_patterns(df)
>>> 'avg_room_occupancy' in seasonal.columns
True