| Title: | Access and Analyse Data from the 'CVD Prevent' API |
|---|---|
| Description: | Provides an R interface to the 'CVD Prevent' application programming interface (API), allowing users to retrieve and analyse cardiovascular disease prevention data from primary care records across England. The Cardiovascular Disease Prevention Audit (CVDPREVENT) automatically extracts routinely held GP health data to support national reporting and improvement initiatives. See the API documentation for details: <https://bmchealthdocs.atlassian.net/wiki/spaces/CP/pages/317882369/CVDPREVENT+API+Documentation>. |
| Authors: | Craig Parylo [aut, cre, cph] (ORCID: <https://orcid.org/0000-0003-4297-7808>), Cardiovascular Disease Prevention Audit (CVDPREVENT) [ant] (Data provider and audit sponsor) |
| Maintainer: | Craig Parylo <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.5 |
| Built: | 2026-06-03 08:16:09 UTC |
| Source: | https://github.com/craig-parylo/cvdprevent |
Returns detailed information about a single NHS area for a given reporting period, including its own details, as well as any parent and child areas. This allows you to understand the heirarchical context (e.g., parent ICB, child PCNs or Practices) for the specified area.
cvd_area_details(time_period_id, area_id)cvd_area_details(time_period_id, area_id)
time_period_id |
Integer (required). The reporting period for which area details should be returned. Use |
area_id |
Integer (required). The AreaID to return details for. Use |
This function is useful for navigating NHS area heirarchies, such as finding all practices within a PCN, or determining the parent ICB for a given area. The result is a list of tibbles, so you can extract and work with each component separately.
A named list with up to three tibbles:
A tibble with details about the specified area.
A tibble with details about the parent area(s), if available.
A tibble with details about child area(s), if available.
If no data is found, returns a tibble describing the error.
area_details, area_parent_details and area_child_details typically contain the following columns:
Character. ONS or internal code for the NHS area (e.g., "E54000015").
Integer. Unique identifier for the NHS area.
Character. Full name of the NHS area (e.g., "NHS Leicester, Leicestershire and Rutland Integrated Care Board").
Character. ODS (Organisation Data Service) code for the area (e.g., "QK1").
Integer. Unique identifier for the system level (e.g., 7 = ICB).
Character. Name of the system level (e.g., "ICB").
See the CVDPREVENT API documentation: Area details
This function may take longer than 5 seconds to complete due to API response time.
cvd_area_list(), cvd_area_unassigned(), cvd_area_search(), cvd_area_nested_subsystems(), cvd_area_flat_subsystems()
# Retrieve details for 'Leicester, Leicestershire and Rutland ICB' (area_id = 8037) # in time period 17 returned_list <- cvd_area_details(time_period_id = 17, area_id = 8037) # View details for the area returned_list$area_details |> dplyr::select(AreaCode, AreaName) # View details for the parent area(s) returned_list$area_parent_details |> dplyr::select(AreaID, AreaName, SystemLevelID) # View details for the child area(s) returned_list$area_child_details |> dplyr::select(AreaID, AreaName, SystemLevelID)# Retrieve details for 'Leicester, Leicestershire and Rutland ICB' (area_id = 8037) # in time period 17 returned_list <- cvd_area_details(time_period_id = 17, area_id = 8037) # View details for the area returned_list$area_details |> dplyr::select(AreaCode, AreaName) # View details for the parent area(s) returned_list$area_parent_details |> dplyr::select(AreaID, AreaName, SystemLevelID) # View details for the child area(s) returned_list$area_child_details |> dplyr::select(AreaID, AreaName, SystemLevelID)
Returns a "flat" list of the specified NHS area and all its immediate child areas from the CVDPREVENT API, with child areas grouped by their system level rather than by strict heirarchical nesting. This function provides a convenient overview when you want to see all sub-areas organised by level (e.g., all PCNs and all GP practices beneath an ICB) without traversing the full heirarchy.
The output is a tibble where each row represents an area or sub-area, and child areas are included as columns (with system level information).
cvd_area_flat_subsystems(area_id)cvd_area_flat_subsystems(area_id)
area_id |
Integer (required). The AreaID for which to retrieve flat sub-system data. use |
This function is useful for quickly listing all areas beneath a parent, grouped by system level, for reporting or selection purposes. For a fully nested view, see cvd_area_nested_subsystems().
A tibble containing details for the specified area and its child areas and child area details (e.g., via SubSystems_* columns). Typical columns include:
Character. Code for the parent NHS area (e.g., "E54000038").
Integer. Unique identifier for the parent NHS area.
Character. Name of the parent NHS area (e.g., "Somerset").
Character. ODS (Organisation Data Service) code for the parent area (e.g., "QSL").
Integer. Identifier for the higher-level parent area (e.g., regional or national grouping).
Character. Code for the subsystem NHS area (e.g., practice or PCN).
Integer. Unique identifier for the subsystem NHS area.
Character. Name of the subsystem NHS area (e.g., "Church Street Surgery, Martock").
Character. ODS code for the subsystem area, if available. Often blank.
Integer. ID of the immediate parent area for the subsystem (e.g., PCN or ICB).
Integer. Identifier for the system level of the subsystem (e.g., 5 = Practice, 4 = PCN).
Character. Name of the system level for the subsystem (e.g., "Practice", "PCN").
Integer. Identifier for the system level of the parent area (e.g., 2 = STP).
Character. Name of the system level for the parent area (e.g., "STP").
If no data is found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Area flat subsystems
This function may take longer than 5 seconds to complete due to API response time.
cvd_area_list(), cvd_area_details(), cvd_area_unassigned(), cvd_area_search(), cvd_area_nested_subsystems()
# View flat sub-systems for Somerset STP (area_id = 5) cvd_area_flat_subsystems(area_id = 5) |> dplyr::glimpse() # View flat sub-systems for Lincolnshire ICB (area_id = 8042) cvd_area_flat_subsystems(area_id = 8042) |> dplyr::glimpse()# View flat sub-systems for Somerset STP (area_id = 5) cvd_area_flat_subsystems(area_id = 5) |> dplyr::glimpse() # View flat sub-systems for Lincolnshire ICB (area_id = 8042) cvd_area_flat_subsystems(area_id = 8042) |> dplyr::glimpse()
Retrieves all NHS geographical areas (e.g., England, Region, ICB, PCN, Practice) that have data avialable for a specified reporting period and either a pareent area or system level. Only areas with data for the chosen time period are returned.
You must specify at least one of parent_area_id or system_level_id. If both are provided, parent_area_id takes precedence and system_level_id is ignored.
If parent_area_id is specified, returns all child areas of the specified parent area.
If system_level_id is specified, returns all areas within that system level.
cvd_area_list(time_period_id, parent_area_id = NULL, system_level_id = NULL)cvd_area_list(time_period_id, parent_area_id = NULL, system_level_id = NULL)
time_period_id |
Integer (required). The reporting period ID for which to return areas. Use |
parent_area_id |
Integer (optional). The AreaID for which all children will be returned. If provided, this takes precedence over |
system_level_id |
Integer (optional). The system level ID for which to return all areas (e.g., Practice, PCN, ICB). Ignored if |
At least one of parent_area_id or system_level_id must be supplied, otherwise an error is thrown.
This function is commonly used to list all practices within a given PCN, all PCNs within an ICB, or all areas at a specific system level for a chosen time period.
A tibble containing area details for the specified criteria with the following columns:
Character. ONS code for the NHS area (e.g., "U91471").
Integer. Unique identifier for the NHS area.
Character. Name of the NHS area (e.g., "Inclusive Health PCN").
Character. ODS (Organisation Data Service) code for the area, if available. Often blank.
Numeric. Percentage of practices or organisations participating in the CVDPREVENT program within the area.
Numeric. Percentage of the population covered by participating organisations in the area.
Integer. Unique identifier for the system level (e.g., 4 = PCN).
Character. Name of the system level (e.g., "PCN").
Integer. ID of the parent organisation or grouping (e.g., ICB or region).
If no data is found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Area lists
This function may take longer than 5 seconds to complete due to API response time.
cvd_area_details(), cvd_area_unassigned(), cvd_area_search(), cvd_area_nested_subsystems(), cvd_area_flat_subsystems()
# List four PCNs (system level 4) with data available at time period 17 cvd_area_list(time_period_id = 17, system_level_id = 4) |> dplyr::select(SystemLevelName, AreaID, AreaCode, AreaName) |> dplyr::slice_head(n = 4) # List all child areas of parent area 8037 (e.g., an ICB) in time period 17 cvd_area_list(time_period_id = 17, parent_area_id = 8037) # Attempting to call without either optional argument will result in a # tibble explaining the error. # cvd_area_list(time_period_id = 17)# List four PCNs (system level 4) with data available at time period 17 cvd_area_list(time_period_id = 17, system_level_id = 4) |> dplyr::select(SystemLevelName, AreaID, AreaCode, AreaName) |> dplyr::slice_head(n = 4) # List all child areas of parent area 8037 (e.g., an ICB) in time period 17 cvd_area_list(time_period_id = 17, parent_area_id = 8037) # Attempting to call without either optional argument will result in a # tibble explaining the error. # cvd_area_list(time_period_id = 17)
Returns a hierarchical (nested) structure of the specified NHS area and all of its descendent (child) areas from the CVDPREVENT API. This function is useful for exploring the parent-child relationships within NHS geographies, such as seeing a PCN and all of its practices, or an ICB with all subordinate structures.
The output is a list of tibbles, one for each "level" in the heirarchy, named as level_1, level_2, etc. Each tibble contains the details for the areas at that level.
cvd_area_nested_subsystems(area_id)cvd_area_nested_subsystems(area_id)
area_id |
Integer (required). The AreaID for which to retrieve nested sub-system data. Use |
This function is helpful for visualising or programmatically traversing the full nested structure beneath a given NHS area. For example, given an ICB, you can see all PCNs, then all practices beneath those PCNs, and so on.
A named list of tibbles, where each element (level_1, level_2, etc.) contains details for the specified area and each subsequent child level.
If no data is found, returns a tibble describing the error.
Each tibble contains the following columns:
Character. Unique code for the NHS area (e.g., "U11103").
Integer. Unique identifier for the NHS area.
Character. Name of the NHS area (e.g., "Yeovil PCN").
Character. ODS (Organisation Data Service) code for the area, if available. Often blank.
Integer. ID of the parent NHS area or organisation (e.g., ICB or region).
Integer. Identifier for the system level (e.g., 4 = PCN).
Character. Name of the system level (e.g., "PCN").
See the CVDPREVENT API documentation: Area nested subsystems
This function may take longer than 5 seconds to complete due to API response time.
cvd_area_list(), cvd_area_details(), cvd_area_unassigned(), cvd_area_search(), cvd_area_flat_subsystems()
# View the nested structure for Somerset STP (area_id = 5) returned_list <- cvd_area_nested_subsystems(area_id = 5) returned_list |> summary() # See details for the first five immediate children of Somerset STP returned_list$level_2 |> dplyr::slice_head(n = 5) # View the nested structure for Leicester Central PCN (area_id = 701) returned_list <- cvd_area_nested_subsystems(area_id = 701) returned_list |> summary() # See the GP practice children of the PCN returned_list$level_2# View the nested structure for Somerset STP (area_id = 5) returned_list <- cvd_area_nested_subsystems(area_id = 5) returned_list |> summary() # See details for the first five immediate children of Somerset STP returned_list$level_2 |> dplyr::slice_head(n = 5) # View the nested structure for Leicester Central PCN (area_id = 701) returned_list <- cvd_area_nested_subsystems(area_id = 701) returned_list |> summary() # See the GP practice children of the PCN returned_list$level_2
Searches for NHS areas whose names match a given partial string, within a specified reporting time period. This function uses a case-insensitive "LIKE" search (i.e., matches any area containing the search term) and returns only areas for which data is available in the specified period.
cvd_area_search(partial_area_name, time_period_id)cvd_area_search(partial_area_name, time_period_id)
partial_area_name |
String (required). The substring to search for within area names (case-insensitive). This may be any part of an area name, e.g., "practice", "PCN", or a specific place. |
time_period_id |
Integer (required). The reporting period (time period) to restrict the search to areas with data. use |
The search is case-insensitive and matches anywhere in the area name.
Only areas with available data in the chosen time period will be returned.
Use this function to quickly locate AreaIDs or codes for use in other cvdprevent API calls.
A tibble containing details of areas matching the search term and having data for the specified time period. Typical columns include:
Character. Unique code for the NHS area (e.g., "P86619").
Integer. Unique identifier for the NHS area
Character. Name of the NHS area (e.g., "Dr Mb Ghafoor & Partners").
Logical or character. Indicates whether the area is visible in the API or dashboard ("Y" or "N").
Logical or character. Indicates whether the area is included in national-level aggregations ("Y" or "N").
Character. ODS (Organisation Data Service) code for the area, if available. Often blank.
Integer. Identifier for the system level (5 = GP Practices).
Character. Name of the system level (e.g., "Practice").
Integer. Display order for the system level in dashboards or reports.
If no data is found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Area search
This function may take longer than 5 seconds to complete due to API response time.
cvd_area_list(), cvd_area_details(), cvd_area_unassigned(), cvd_area_nested_subsystems(), cvd_area_flat_subsystems()
# Search for areas containing "practice" in their name for time period 17 cvd_area_search(partial_area_name = "practice", time_period_id = 17) |> dplyr::select(AreaID, AreaName, AreaCode) # Search for areas containing "PCN" for time period 17 cvd_area_search(partial_area_name = "PCN", time_period_id = 17) |> dplyr::select(AreaID, AreaName, AreaCode)# Search for areas containing "practice" in their name for time period 17 cvd_area_search(partial_area_name = "practice", time_period_id = 17) |> dplyr::select(AreaID, AreaName, AreaCode) # Search for areas containing "PCN" for time period 17 cvd_area_search(partial_area_name = "PCN", time_period_id = 17) |> dplyr::select(AreaID, AreaName, AreaCode)
Retrieves all available NHS system levels (e.g., National, Region, ICB, PCN, Practice) for a specified reporting time period from the CVDPREVENT API.
This function helps users determine which system levels are available for data extraction in a given reporting period.
cvd_area_system_level(time_period_id)cvd_area_system_level(time_period_id)
time_period_id |
Integer (required). The ID of the reporting time period for which system levels should be returned. Use |
This function is useful in workflows where you need to filter or subset NHS areas or data by both time period and system level. It is often used as a precursor to more detailed area or indicator queries.
A tibble containing system level details for the specified time period, with the following columns:
Logical or character. Indicates whether the system level is visible in the API or dashboard ("Y" or "N").
Logical or character. Indicates whether the system level represents national coverage ("Y" or "N").
Integer. Unique identifier for the system level (e.g., 1 = England, 4 = PCN).
Character. Name of the system level (e.g., "England", "Region", "ICB", "Practice").
Integer. Display order for the system level in dashboards or reports.
If no data is found, returns a tibble describing the error.
See the CVDPREVENT API documentation: System levels per time period
This function may take longer than 5 seconds to complete due to API response time.
cvd_area_details(), cvd_area_unassigned(), cvd_area_search(), cvd_area_nested_subsystems(), cvd_area_flat_subsystems(), cvd_time_period_system_levels()
# List all system levels available for time period 4 (activity to March 2022) cvd_area_system_level(time_period_id = 4) |> dplyr::select(SystemLevelID, SystemLevelName) # Find valid time period IDs, then get system levels for the latest one latest_period <- cvd_time_period_list() |> dplyr::pull(TimePeriodID) |> max() cvd_area_system_level(time_period_id = latest_period) |> dplyr::select(SystemLevelID, SystemLevelName)# List all system levels available for time period 4 (activity to March 2022) cvd_area_system_level(time_period_id = 4) |> dplyr::select(SystemLevelID, SystemLevelName) # Find valid time period IDs, then get system levels for the latest one latest_period <- cvd_time_period_list() |> dplyr::pull(TimePeriodID) |> max() cvd_area_system_level(time_period_id = latest_period) |> dplyr::select(SystemLevelID, SystemLevelName)
Retrieves all available NHS system levels from the CVDPREVENT API, along with the reporting periods (time periods) in which each system level has data available.
This function is the inverse of cvd_time_period_system_levels(), allowing you to see, for each system level (e.g., National, Region, ICB, PCN, Practice), the set of time periods for which data exists.
cvd_area_system_level_time_periods()cvd_area_system_level_time_periods()
Use this function to determine which reporting periods are available for each NHS system level. This is useful for dynamically generating data selections or validating user input in dashboards or scripts.
A tibble with one row per system level and time period, with the following columns:
Logical or character. Indicates whether the time period is visible in the API or dashboard ("Y" or "N").
Logical or character. Indicates whether the data is available at the national level ("Y" or "N").
Integer. Unique identifier for the system level (e.g., 1 = England, 4 = PCN).
Character. Name of the system level (e.g., "England", "ICB", "Sub-ICB", "STP").
POSIXct. End date of the reporting period (e.g., "2023-06-30").
POSIXct. Start date of the reporting period. Typically set to a default baseline (e.g., "1900-01-01").
Integer. Unique identifier for the time period.
Character. Display label for the time period (e.g., "To June 2025", "Apr 2022 – Mar 2023").
If no data is found, returns a tibble describing the error.
CVDPREVENT API documentation: All system levels and time periods for details.
This function may take longer than 5 seconds to complete due to API response time.
cvd_time_period_system_levels(), cvd_area_details(), cvd_area_unassigned(), cvd_area_search(), cvd_area_nested_subsystems(), cvd_area_flat_subsystems()
# List the latest four reporting periods at GP practice level cvd_area_system_level_time_periods() |> dplyr::filter(SystemLevelName == "Practice") |> dplyr::slice_max(order_by = TimePeriodID, n = 4) |> dplyr::select(SystemLevelName, TimePeriodID, TimePeriodName) # Explore all system levels and their available time periods cvd_area_system_level_time_periods()# List the latest four reporting periods at GP practice level cvd_area_system_level_time_periods() |> dplyr::filter(SystemLevelName == "Practice") |> dplyr::slice_max(order_by = TimePeriodID, n = 4) |> dplyr::select(SystemLevelName, TimePeriodID, TimePeriodName) # Explore all system levels and their available time periods cvd_area_system_level_time_periods()
Retrieves all NHS areas that have data in the specified reporting time period but do not have any parent areas assigned. These "unassigned" areas are unreachable via standard heirarchical navigation and may represent data issues or exceptional cases (e.g., England as the highest-level system).
cvd_area_unassigned(time_period_id, system_level_id = NULL)cvd_area_unassigned(time_period_id, system_level_id = NULL)
time_period_id |
Integer (required). The reporting period (time period) for which to find unassigned areas. Use |
system_level_id |
Integer (optional). Restrict the search to areas at a specific system level (e.g., Practice, PCN, ICB). Use |
Use this function to identify "orphaned" NHS areas or to understand top-level areas (e.g., England).
If system_level_id = 1 (England), expect the only result to be England, since it has no parent.
This can help with data quality checks or to ensure all areas are accessible via parent/child navigation.
A tibble containing details for all areas without parent assignments in the selected time period (and system level, if specified). Typical columns include:
Character. Unique code for the NHS area (e.g., "L81117").
Integer. Unique identifier for the NHS area
Character. Name of the NHS area (e.g., "Pilning Surgery").
Character. ODS (Organisation Data Service) code for the practice, if available. Often blank.
Integer. Identifier for the system level (5 = GP practices).
Character. Name of the system level (e.g., "Practice").
If no data is found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Areas unassigned
This function may take longer than 5 seconds to complete due to API response time.
cvd_area_list(), cvd_area_details(), cvd_area_search(), cvd_area_nested_subsystems(), cvd_area_flat_subsystems()
# Report four GP practices (system level ID = 5) without parent PCN details for time period 17: cvd_area_unassigned(time_period_id = 17, system_level_id = 5) |> dplyr::slice_head(n = 4) |> dplyr::select(SystemLevelName, AreaID, AreaName) # List unassigned top-level areas (system level ID = 1, England) for time period 17: cvd_area_unassigned(time_period_id = 17, system_level_id = 1) |> dplyr::select(SystemLevelName, AreaID, AreaName)# Report four GP practices (system level ID = 5) without parent PCN details for time period 17: cvd_area_unassigned(time_period_id = 17, system_level_id = 5) |> dplyr::slice_head(n = 4) |> dplyr::select(SystemLevelName, AreaID, AreaName) # List unassigned top-level areas (system level ID = 1, England) for time period 17: cvd_area_unassigned(time_period_id = 17, system_level_id = 1) |> dplyr::select(SystemLevelName, AreaID, AreaName)
Remove all entries from the memoise cache used by cvdprevent.
cvd_clear_cache()cvd_clear_cache()
This function forces the package cache to be emptied. It is safe to call from interactive sessions, non-interactive checks and tests. Clearing the cache does not change any package options or remove the cache directory; it only removes the stored key/value entries so subsequent calls will re-query the API.
Use this when you want to:
force fresh API requests or recomputation during development
clear stale or corrupted cache contents before running checks
free disc space used by the cache
Invisibly returns TRUE on success
## Not run: # Clear cache cvd_clear_cache() ## End(Not run)## Not run: # Clear cache cvd_clear_cache() ## End(Not run)
Returns the data availability.
Response:
DataAvailabilityID - ID of the resource as found in the database
DataAvailabilityName - explanation for the data availability
IsAvailable - Y for data is available, N for data is unavailable, and NULL for unknown data
cvd_data_availability( time_period_id, system_level_id, indicator_id = NULL, metric_category_type_id = NULL )cvd_data_availability( time_period_id, system_level_id, indicator_id = NULL, metric_category_type_id = NULL )
time_period_id |
integer - the time period to return data for (compulsory) |
system_level_id |
integer - the system level to return data for (compulsory) |
indicator_id |
integer - the indicator to return data for (optional) |
metric_category_type_id |
integer - the metric category to return data for (optional) |
CVD Prevent API documentation: Data availability
Tibble of data availability
This function may take longer than 5 seconds to complete due to API response time.
cvd_data_availability(time_period_id = 3, system_level_id = 5)cvd_data_availability(time_period_id = 3, system_level_id = 5)
Returns a tibble containing metadata for all external resources referenced by the CVDPREVENT programme. These resources may include clinical guidelines, research papers, policy documents, and third-party datasets used to support indicator definitions and reporting.
cvd_external_resource()cvd_external_resource()
Each resource is categorised and includes source information, title, and descriptive metadata. This function is useful for:
Auditing external references used in CVDPREVENT indicators
Linking indicators to supporting evidence or policy
Building documentation or dashboards that reference external sources
A tibble where each row represents an external resource referenced by CVDPREVENT. Columns include:
Character. Thematic category of the resource (e.g., "Toolkits", "Resources for patients").
Integer. Unique identifier for the resource.
Integer. Display order for the resource within its category.
Character. Organisation or publisher of the resource (e.g., "NHS England", "UCLPartners").
Character. Title of the resource (e.g., "Cardiovascular Disease Prevention Data Packs").
Character. Type of resource (e.g., "website", "document").
Character. Direct URL to the resource.
List-column of data frames. Each entry contains one or more indicator tags associated with the resource, including:
Integer. Unique identifier for the tag.
Character. Descriptive name of the tag (e.g., "prevention", "digital tools").
May be empty or contain NA if no tags are assigned.
If the request fails, a tibble describing the error is returned instead.
See the CVDPREVENT API documentation: External resources
This function may take longer than 5 seconds to complete due to API response time.
cvd_data_availability() for checking data coverage across indicators
# Show the first five external resources grouped by category cvd_external_resource() |> dplyr::filter(ExternalResourceID < 10) |> dplyr::select(ExternalResourceCategory, ExternalResourceSource, ExternalResourceTitle) |> dplyr::group_by(ExternalResourceCategory)# Show the first five external resources grouped by category cvd_external_resource() |> dplyr::filter(ExternalResourceID < 10) |> dplyr::select(ExternalResourceCategory, ExternalResourceSource, ExternalResourceTitle) |> dplyr::group_by(ExternalResourceCategory)
Returns all CVD indicators and related data for a specified reporting period (time_period_id) and NHS area (area_id) from the CVDPREVENT API. Also retrieves time series data for all available periods. Optionally, you can filter results by one or more indicator tags.
The returned object is a named list of tibbles, including details about indicators, metric categories, metric data and time series, making this function ideal for comprehensive data extraction and downstream analysis.
cvd_indicator(time_period_id, area_id, tag_id = NULL)cvd_indicator(time_period_id, area_id, tag_id = NULL)
time_period_id |
Integer (required). The reporting period (time period) for which to return indicator data. Use the |
area_id |
Integer (required). The AreaID for which to return indicator data. Use |
tag_id |
Numeric vector (optional). One or more tag IDs to filter indicators by tag. Use |
This function is useful for extracting all indicator data for a given area and period, including breakdowns by category and time series. The list output allows easy access to different data tables for further analysis or visualisation. Filtering by tag enables targeted queries for specific subsets of indicators.
A named list containing up to four tibbles:
Tibble of indicators for the area and time period.
Tibble of metric categories related to the indicators.
Tibble of metric values for the area and indicators.
Tibble of time series data for metrics and indicators across time periods.
If no indicators are found, returns a tibble describing the error.
indicators contains the following columns:
Character. Symbol used to represent the metric axis (e.g., "%").
Character. Frequency or interval at which the indicator data is updated. Often blank.
Character. Display format for the metric (e.g., "Proportion %").
Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
Character. Unique code for the indicator (e.g., "CVDP009CHOL").
Integer. Internal ID for the indicator's format type.
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Display order for the indicator in dashboards or reports.
Character. Abbreviated name of the indicator for display purposes.
Character. Status of the indicator (e.g., active, discontinued). Often blank.
Integer. Unique identifier for the indicator type (e.g., 1 = Standard).
Character. Name of the indicator type (e.g., "Standard").
Integer. Count of notifications associated with the indicator.
metric_categories contains the following columns:
Integer. Unique identifier for the indicator. Links to the corresponding entry in the indicators table.
Character. Grouping label used to define the population subset (e.g., "Male", "Persons").
Integer. Unique identifier for the metric category.
Character. Name of the subgroup or category (e.g., "80+", "Mixed", "Female").
Integer. Display order for the category within its type.
Character. Type of category used for breakdown (e.g., "Age group", "Sex", "Ethnicity").
Integer. Unique identifier for the specific metric instance.
metric_data contains the following columns:
Integer. Unique identifier for the metric instance. Links to the corresponding entry in the metric categories table.
Integer. Unique identifier for the NHS area.
Integer. Number of records included in the calculation.
Integer. Unique identifier for the data point.
Numeric. Denominator used in the metric calculation.
Numeric. Scaling factor applied to the metric, if applicable. Often blank.
Numeric. Lower bound of the confidence interval.
Numeric. Maximum observed value for the metric.
Numeric. Median value for the metric.
Numeric. Minimum observed value for the metric.
Numeric. Numerator used in the metric calculation.
Numeric. 20th percentile value.
Numeric. 40th percentile value.
Numeric. 60th percentile value.
Numeric. 80th percentile value.
Integer. Identifier for the time period associated with the metric.
Numeric. Upper bound of the confidence interval.
Numeric. Final calculated value for the metric.
Character. Notes or flags associated with the value (e.g., suppression warnings).
timeseries_data contains the following columns:
Integer. Unique identifier for the metric instance. Links to the corresponding entry in the metric data table.
POSIXct. End date of the reporting period (e.g., "2025-06-30").
Numeric. Median value for the metric during the specified time period.
POSIXct. Start date of the reporting period. Typically set to a default baseline (e.g., "1900-01-01").
Integer. Unique identifier for the time period.
Character. Display label for the time period (e.g., "To June 2025").
Numeric. Final calculated value for the metric in the given time period.
See the CVDPREVENT API documentation: Indicator
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_metric_list(), cvd_indicator_tags(), cvd_indicator_details(), cvd_indicator_sibling(), cvd_indicator_child_data(), cvd_indicator_data(), cvd_indicator_metric_data(), cvd_indicator_raw_data(), cvd_indicator_nationalarea_metric_data(), cvd_indicator_priority_groups(), cvd_indicator_pathway_group(), cvd_indicator_group(), cvd_indicator_metric_timeseries(), cvd_indicator_person_timeseries(), cvd_indicator_metric_systemlevel_comparison(), cvd_indicator_metric_area_breakdown()
# Get all indicator data for area_id = 1103 in time period 17 return_list <- cvd_indicator(time_period_id = 17, area_id = 1103) # See what data tables are available summary(return_list) # Extract and examine indicators indicators <- return_list$indicators indicators |> dplyr::select(IndicatorID, IndicatorCode, IndicatorShortName) |> dplyr::arrange(IndicatorID) |> dplyr::slice_head(n = 4) # Extract metric categories for a specific indicator and categories categories <- return_list$metric_categories categories |> dplyr::filter(IndicatorID == 7, MetricCategoryID %in% c(7, 8)) |> dplyr::select( IndicatorID, MetricCategoryTypeName, CategoryAttribute, MetricCategoryName, MetricID ) # Extract metric data for specific metrics metric_data <- return_list$metric_data metric_data |> dplyr::filter(MetricID %in% c(126, 132)) |> dplyr::select(MetricID, Value, Numerator, Denominator) # Extract time series data for selected metrics timeseries_data <- return_list$timeseries_data timeseries_data |> dplyr::filter(MetricID %in% c(126, 132), !is.na(Value)) # Filter by tags: get indicators tagged with either tag 3 or 4 in area 3, time period 17 return_list <- cvd_indicator(time_period_id = 17, area_id = 3, tag_id = c(3, 4))# Get all indicator data for area_id = 1103 in time period 17 return_list <- cvd_indicator(time_period_id = 17, area_id = 1103) # See what data tables are available summary(return_list) # Extract and examine indicators indicators <- return_list$indicators indicators |> dplyr::select(IndicatorID, IndicatorCode, IndicatorShortName) |> dplyr::arrange(IndicatorID) |> dplyr::slice_head(n = 4) # Extract metric categories for a specific indicator and categories categories <- return_list$metric_categories categories |> dplyr::filter(IndicatorID == 7, MetricCategoryID %in% c(7, 8)) |> dplyr::select( IndicatorID, MetricCategoryTypeName, CategoryAttribute, MetricCategoryName, MetricID ) # Extract metric data for specific metrics metric_data <- return_list$metric_data metric_data |> dplyr::filter(MetricID %in% c(126, 132)) |> dplyr::select(MetricID, Value, Numerator, Denominator) # Extract time series data for selected metrics timeseries_data <- return_list$timeseries_data timeseries_data |> dplyr::filter(MetricID %in% c(126, 132), !is.na(Value)) # Filter by tags: get indicators tagged with either tag 3 or 4 in area 3, time period 17 return_list <- cvd_indicator(time_period_id = 17, area_id = 3, tag_id = c(3, 4))
Returns the value of a single metric for all child areas of a specified NHS area (and the specified area itself) for a chosen reporting period, using the CVDPREVENT API. This function enables direct comparison of a specific metric across all subordinate areas (e.g., all GP practices within a PCN, or all PCNs within an ICB).
Only the selected metric is returned for each child area.
cvd_indicator_child_data(time_period_id, area_id, metric_id)cvd_indicator_child_data(time_period_id, area_id, metric_id)
time_period_id |
Integer (required). The reporting period (time period) for which to return child data. Use |
area_id |
Integer (required). The AreaID for which to find child areas. Use |
metric_id |
Integer (required). The MetricID for which to retrieve values. Use |
Use this function to compare a metric across all immediate child areas under a parent (for example, to benchmark all GP practices within a PCN for a specific indicator and reporting period).
A tibble with the value of the specified metric for the given area and all its child areas, for the specified time period. Columns include:
Character. Grouping label used to define the population subset (e.g., "Male").
Character. Unique code for the indicator (e.g., "CVDP002AF").
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Display order for the indicator in dashboards or reports.
Character. Abbreviated name of the indicator for display purposes.
Integer. Unique identifier for the metric category.
Character. Name of the subgroup or category (e.g., "40–59").
Integer. Display order for the category within its type.
Character. Type of category used for breakdown (e.g., "Age group").
Character. Code for the child NHS area (e.g., PCN).
Integer. Unique identifier for the child NHS area.
Character. Name of the child NHS area (e.g., "Teldoc PCN").
Integer. Number of records included in the calculation.
Integer. Unique identifier for the data point.
Numeric. Denominator used in the metric calculation.
Numeric. Scaling factor applied to the metric, if applicable. Often blank.
Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
Numeric. Lower bound of the confidence interval.
Numeric. Maximum observed value for the metric.
Numeric. Median value for the metric.
Numeric. Minimum observed value for the metric.
Integer. Count of notifications associated with the indicator.
Numeric. Numerator used in the metric calculation.
Numeric. 20th percentile value.
Numeric. 40th percentile value.
Numeric. 60th percentile value.
Numeric. 80th percentile value.
Integer. Identifier for the system level (e.g., 4 = PCN).
Character. Name of the system level (e.g., "PCN").
Integer. Identifier for the time period associated with the metric.
Character. Display label for the time period (e.g., "To March 2024").
Numeric. Upper bound of the confidence interval.
Numeric. Final calculated value for the metric.
Character. Notes or flags associated with the value (e.g., suppression warnings).
If no child data is found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Indicator child data
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_metric_list(), cvd_indicator(), cvd_indicator_tags(), cvd_indicator_details(), cvd_indicator_sibling(), cvd_indicator_data(), cvd_indicator_metric_data(), cvd_indicator_raw_data(), cvd_indicator_nationalarea_metric_data(), cvd_indicator_priority_groups(), cvd_indicator_pathway_group(), cvd_indicator_group(), cvd_indicator_metric_timeseries(), cvd_indicator_person_timeseries(), cvd_indicator_metric_systemlevel_comparison(), cvd_indicator_metric_area_breakdown()
# Compare the value of metric 126 for area 74 and all its child areas in time period 22 cvd_indicator_child_data(time_period_id = 22, area_id = 74, metric_id = 126) |> dplyr::select(AreaID, AreaName, Value, LowerConfidenceLimit, UpperConfidenceLimit) # Find a valid metric ID for an indicator, then get child area data metrics <- cvd_indicator_metric_list(time_period_id = 17, system_level_id = 5) metric_id <- metrics$MetricID[1] cvd_indicator_child_data(time_period_id = 17, area_id = 1103, metric_id = metric_id)# Compare the value of metric 126 for area 74 and all its child areas in time period 22 cvd_indicator_child_data(time_period_id = 22, area_id = 74, metric_id = 126) |> dplyr::select(AreaID, AreaName, Value, LowerConfidenceLimit, UpperConfidenceLimit) # Find a valid metric ID for an indicator, then get child area data metrics <- cvd_indicator_metric_list(time_period_id = 17, system_level_id = 5) metric_id <- metrics$MetricID[1] cvd_indicator_child_data(time_period_id = 17, area_id = 1103, metric_id = metric_id)
Fetches all available metric breakdowns for a single cardiovascular disease (CVD) indicator from the CVDPREVENT API, scoped to a specified NHS area and reporting period. This includes subgroup data such as age, sex, ethnicity, deprivation quintile, and more.
cvd_indicator_data(time_period_id, area_id, indicator_id)cvd_indicator_data(time_period_id, area_id, indicator_id)
time_period_id |
Integer (required). The reporting period (time period) to retrieve data for. Use |
area_id |
Integer (required). The AreaID for which to retrieve indicator data. use |
indicator_id |
Integer (required). The IndicatorID for which to retrieve data. use |
Use this function to obtain all metric values for a single indicator in a particular area and time period, such as for a local dashboard or a focussed report. For broader queries across multiple indicators, see cvd_indicator() or cvd_indicator_metric_list().
A named list containing three tibbles:
Tibble. Metadata and definitions for the selected indicator and its associated metrics.
Tibble. Metric values for the specified NHS area (area_id) across all available breakdowns.
Tibble. Metric values for England, used for benchmarking and comparison.
If no indicator data is found, returns a tibble describing the error.
indicator_metrics contains the following items:
Character. Symbol used to represent the metric axis (e.g., "%").
Character. Display format for the metric (e.g., "Proportion %").
Character. Unique code for the indicator (e.g., "CVDP002AF").
Integer. Internal ID for the indicator's format type.
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Display order for the indicator in dashboards or reports.
Character. Abbreviated name of the indicator for display.
Integer. Count of notifications associated with the indicator. Often zero.
Integer. ID of the reporting time period.
Character. Label for the reporting time period (e.g., "To March 2024").
Character. Subgroup label (e.g., "Male", "Female", "Persons").
Integer. Unique ID for the metric category.
Character. Name of the subgroup or category (e.g., "18–39", "Sex").
Integer. Display order for the metric category.
Character. Type of subgroup (e.g., "Age group", "Sex").
Integer. Unique ID for the specific metric being measured.
area_data and national_data contain the following items:
Integer. Unique identifier for the metric being measured.
Character. Type of subgroup (e.g., "Sex", "Age group").
Character. Name of the subgroup (e.g., "Female", "18–39").
Character. Label used to group individuals (e.g., "Male", "Persons").
Character. ONS code for the NHS area (e.g., "U60176").
Integer. Internal ID for the NHS area.
Character. Name of the NHS area (e.g., "3 Centres PCN").
Integer. Total number of individuals in the subgroup.
Integer. Unique identifier for the data record.
Numeric. Population or count used as the denominator in metric calculation.
Numeric. Scaling factor applied to the metric, if applicable. Often NA.
Character. Notification priority level, if available. Often NA.
Numeric. Lower bound of the confidence interval for the metric value.
Numeric. Maximum observed value for the metric across comparable areas.
Numeric. Median value for the metric across comparable areas.
Numeric. Minimum observed value for the metric across comparable areas.
Integer. Count of notifications associated with the indicator. Often zero.
Numeric. Count used as the numerator in metric calculation.
Numeric. 20th percentile value across comparable areas.
Numeric. 40th percentile value across comparable areas.
Numeric. 60th percentile value across comparable areas.
Numeric. 80th percentile value across comparable areas.
Integer. ID of the reporting time period.
Character. Label for the reporting time period (e.g., "To March 2024").
Numeric. Upper bound of the confidence interval for the metric value.
Numeric. Calculated metric value (e.g., percentage of patients treated).
Character. Additional notes or flags about the value. Often NA.
See the CVDPREVENT API documentation: Indicator data
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_metric_list(), cvd_indicator(), cvd_indicator_tags(), cvd_indicator_details(), cvd_indicator_sibling(), cvd_indicator_child_data(), cvd_indicator_metric_data(), cvd_indicator_raw_data(), cvd_indicator_nationalarea_metric_data(), cvd_indicator_priority_groups(), cvd_indicator_pathway_group(), cvd_indicator_group(), cvd_indicator_metric_timeseries(), cvd_indicator_person_timeseries(), cvd_indicator_metric_systemlevel_comparison(), cvd_indicator_metric_area_breakdown()
# Retrieve all metric breakdowns for indicator 7 in area 1103 for time period 17 returned_list <- cvd_indicator_data(time_period_id = 17, area_id = 1103, indicator_id = 7) # See the structure of this data returned_list |> dplyr::glimpse() # See the definition for one metric returned_list$indicator_metrics |> dplyr::slice_head(n = 1) |> dplyr::glimpse() # Compare performance in the specified area (AreaID = 1103) with national results for # women aged 40-59 years (MetricID = 132) dplyr::bind_rows( returned_list$area_data, returned_list$national_data ) |> dplyr::filter(MetricID == 132)# Retrieve all metric breakdowns for indicator 7 in area 1103 for time period 17 returned_list <- cvd_indicator_data(time_period_id = 17, area_id = 1103, indicator_id = 7) # See the structure of this data returned_list |> dplyr::glimpse() # See the definition for one metric returned_list$indicator_metrics |> dplyr::slice_head(n = 1) |> dplyr::glimpse() # Compare performance in the specified area (AreaID = 1103) with national results for # women aged 40-59 years (MetricID = 132) dplyr::bind_rows( returned_list$area_data, returned_list$national_data ) |> dplyr::filter(MetricID == 132)
Returns metadata and descriptive information for a single CVD indicator, identified by its IndicatorID, from the CVDPREVENT API. This function allows you to programmatically access the definitions, titles and metadata fields associated with specific indicators for use in reporting, dashboards or documentation.
cvd_indicator_details(indicator_id)cvd_indicator_details(indicator_id)
indicator_id |
Integer (required). The IndicatorID for which to return details. Use |
Use this function to retrieve indicator definitions, full names, and metadata fields for use in custom reports or to provide documentation / tooltips in analytical applications. Metadata fields are unnested for convenience.
A tibble containing metadata and details for the specified indicator containing the following columns:
Character. Unique code for the indicator (e.g., "CVDP002AF").
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Display order for the indicator in dashboards or reports.
Character. Abbreviated name of the indicator for display purposes.
Integer. Count of notifications associated with the indicator.
Character. Indicates whether the indicator is age-standardised ("Y" or "N").
Character. Section heading or thematic grouping for the metadata (e.g., "Section 2: Data and Construction").
Character. Detailed explanatory text or notes associated with the indicator. May include rationale, definitions, sources, or caveats.
Integer. Unique identifier for the metadata category.
Character. Title or label describing the metadata content (e.g., "Rationale", "Disclosure control").
If no indicator details are found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Indicator details
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_metric_list(), cvd_indicator(), cvd_indicator_tags(), cvd_indicator_sibling(), cvd_indicator_child_data(), cvd_indicator_data(), cvd_indicator_metric_data(), cvd_indicator_raw_data(), cvd_indicator_nationalarea_metric_data(), cvd_indicator_priority_groups(), cvd_indicator_pathway_group(), cvd_indicator_group(), cvd_indicator_metric_timeseries(), cvd_indicator_person_timeseries(), cvd_indicator_metric_systemlevel_comparison(), cvd_indicator_metric_area_breakdown()
# Retrieve details for indicator with ID 7 cvd_indicator_details(indicator_id = 7) |> dplyr::select(IndicatorID, MetaDataTitle, MetaData) |> dplyr::slice_head(n = 5) # Find a valid indicator ID, then get its details indicators <- cvd_indicator_list(time_period_id = 17, system_level_id = 5) cvd_indicator_details(indicator_id = indicators$IndicatorID[1])# Retrieve details for indicator with ID 7 cvd_indicator_details(indicator_id = 7) |> dplyr::select(IndicatorID, MetaDataTitle, MetaData) |> dplyr::slice_head(n = 5) # Find a valid indicator ID, then get its details indicators <- cvd_indicator_list(time_period_id = 17, system_level_id = 5) cvd_indicator_details(indicator_id = indicators$IndicatorID[1])
Returns a tibble of indicators belonging to a single indicator group, identified by its group ID. Indicator groups are thematic collections of indicators used throughout CVDPREVENT reporting, such as "Monitoring", "Diagnosis", or "Management". This function enables users to explore the structure and contents of these groups, including their type and display order.
cvd_indicator_group(indicator_group_id)cvd_indicator_group(indicator_group_id)
indicator_group_id |
Integer (required). The ID of the indicator group to retrieve. |
Indicator groups are defined in the CVDPREVENT IndicatorGroup table and include metadata such as:
IndicatorGroupName: the name of the group (e.g., "Monitoring")
IndicatorGroupTypeID: the type of group (e.g., Priority Group, Key Question Group)
IndicatorGroupTypeName: the readable label for the group type
Each group contains an array of indicators, which are returned with their associated metadata. This function is useful for:
Exploring which indicators belong to a specific clinical theme
Building dashboards or reports based on grouped indicators
Understanding how indicators are organised within the CVDPREVENT framework
To find valid indicator_group_id values, use cvd_indicator_priority_groups().
A tibble where each row represents an indicator within the specified indicator group. Columns include:
Integer. Unique identifier for the indicator group (e.g., 1 for "ABC").
Character. Name of the indicator group (e.g., "Prevalence", "Smoking and BMI").
Integer. Identifier for the type of indicator group (e.g., 1 = Priority Group).
Character. Descriptive name of the group type (e.g., "Priority Group").
Integer. Display order of the indicator within the group.
Character. Notification priority level, if applicable (e.g., "Red", "Blue"). Often blank.
Character. Unique code for the indicator (e.g., "CVDP004HYP").
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Unique identifier for the associated metric.
Integer. Count of notifications associated with the indicator.
If the request fails or the ID is invalid, a tibble with error details is returned instead.
See the CVDPREVENT API documentation: indicator group
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_priority_groups() to browse available indicator groups,
cvd_indicator_list() to view all indicators,
cvd_indicator_data() to retrieve metric values,
cvd_indicator_details() for indicator metadata,
cvd_indicator_pathway_group() for pathway-based groupings
# list the indicators under Indicator Group ID 13 (Monitoring) which lists # 'Key Question' Indicator Group indicators: cvd_indicator_group(indicator_group_id = 13) |> dplyr::select(IndicatorGroupID, IndicatorGroupName, IndicatorGroupTypeName, IndicatorID, IndicatorName)# list the indicators under Indicator Group ID 13 (Monitoring) which lists # 'Key Question' Indicator Group indicators: cvd_indicator_group(indicator_group_id = 13) |> dplyr::select(IndicatorGroupID, IndicatorGroupName, IndicatorGroupTypeName, IndicatorID, IndicatorName)
Retrieves basic details for all CVD indicators available for a given system level and reportion period from the CVDPREVENT API. Only indicators with data for the selected time period and system level are returned. This function is commonly used to populate indicator pickers or to discover what data is available for further queries.
cvd_indicator_list(time_period_id, system_level_id)cvd_indicator_list(time_period_id, system_level_id)
time_period_id |
Integer (required). The reporting period (time period) for which to return indicators. Use |
system_level_id |
Integer (required). The system level (e.g., National, Region, ICB, PCN, Practice) for which to return indicators. Use |
Use this function to discover which indicators are available for a specific combination of system level and time period. The results can be joined with other outputs for further analysis, or used as the basis for more detailed indicator, metric, or data queries.
A tibble with one row per available indicator for the specified system level and time period. Typical columns include:
Character. Symbol used to represent the metric axis (e.g., "%").
Character. Frequency or interval at which the indicator data is updated. Often blank.
Character. Display format for the metric (e.g., "Proportion %").
Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
Character. Unique code for the indicator (e.g., "CVDP005CKD").
Integer. Internal ID for the indicator's format type.
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Display order for the indicator in dashboards or reports.
Character. Abbreviated name of the indicator for display purposes.
Character. Status of the indicator (e.g., active, retired). Often blank.
Integer. Count of notifications associated with the indicator.
If no indicators are found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Indicator list
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_metric_list(), cvd_indicator(), cvd_indicator_tags(), cvd_indicator_details(), cvd_indicator_sibling(), cvd_indicator_child_data(), cvd_indicator_data(), cvd_indicator_metric_data(), cvd_indicator_raw_data(), cvd_indicator_nationalarea_metric_data(), cvd_indicator_priority_groups(), cvd_indicator_pathway_group(), cvd_indicator_group(), cvd_indicator_metric_timeseries(), cvd_indicator_person_timeseries(), cvd_indicator_metric_systemlevel_comparison(), cvd_indicator_metric_area_breakdown()
# List four indicators for time period 17 and GP practice level (system level 5) cvd_indicator_list(time_period_id = 17, system_level_id = 5) |> dplyr::select(IndicatorID, IndicatorCode, IndicatorShortName) |> dplyr::slice_head(n = 4) # Find valid time period and system level IDs, then list all available indicators valid_periods <- cvd_time_period_list() valid_levels <- cvd_area_system_level(time_period_id = 17) cvd_indicator_list(time_period_id = 17, system_level_id = valid_levels$SystemLevelID[1])# List four indicators for time period 17 and GP practice level (system level 5) cvd_indicator_list(time_period_id = 17, system_level_id = 5) |> dplyr::select(IndicatorID, IndicatorCode, IndicatorShortName) |> dplyr::slice_head(n = 4) # Find valid time period and system level IDs, then list all available indicators valid_periods <- cvd_time_period_list() valid_levels <- cvd_area_system_level(time_period_id = 17) cvd_indicator_list(time_period_id = 17, system_level_id = valid_levels$SystemLevelID[1])
Returns a tibble showing the performance of a specified metric for a given NHS area, alongside national-level data and other areas within the same system level (e.g., PCNs within an ICB). This function powers the Area Breakdown chart in CVDPREVENT reporting.
cvd_indicator_metric_area_breakdown(time_period_id, area_id, metric_id)cvd_indicator_metric_area_breakdown(time_period_id, area_id, metric_id)
time_period_id |
Integer (required). The ID of the reporting period. Use |
area_id |
Integer (required). The ID of the NHS area to anchor the comparison. Use |
metric_id |
Integer (required). The ID of the metric to retrieve. Use |
The output includes:
Metric values for the selected area
Comparison with national performance (AreaID = 1)
Peer areas within the same system level
Target thresholds (if defined)
This function is useful for:
Benchmarking local performance against national and peer averages
Identifying variation within a system level
Supporting targeted improvement and equity analysis
To find valid metric_id values, use cvd_indicator_metric_list() or cvd_indicator_data().
For valid area_id values, use cvd_area_list() or cvd_area_search().
For valid time_period_id values, use cvd_time_period_list().
A tibble comparing metric performance for a specified NHS area and the national aggregate. Each row represents one area (local or national) and includes the following columns:
Character. Indicates whether the row represents national-level data ("Y" for national, "N" for local).
Integer. Identifier for the system level (e.g., 1 = England, 4 = PCN).
Numeric. Median value for the metric across all areas in the system level.
Character. Name of the system level (e.g., "England", "PCN").
Integer. Display order for the system level.
Character. Descriptive label for the target threshold (e.g., "Upper threshold for QOF").
Numeric. Target value to be achieved (e.g., 95).
Character. Code for the NHS area (e.g., "U60510" for a PCN, "E92000001" for England).
Integer. Unique identifier for the NHS area.
Character. Name of the NHS area (e.g., "Salford South East PCN").
Numeric. Final calculated value for the metric in the area.
If no data is available for the given parameters, a tibble describing the error is returned.
See the CVDPREVENT API documentation: Indicator metric area breakdown
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_metric_list() to browse available metrics,
cvd_area_list() and cvd_area_search() to find valid area IDs,
cvd_time_period_list() to explore reporting periods,
cvd_indicator_metric_systemlevel_comparison() for peer-level comparisons,
cvd_indicator_metric_timeseries() for longitudinal analysis,
cvd_indicator_priority_groups() for grouped indicator metadata
# Compare performance for metric ID 128 in time period 17 for # Salford South East PCN (area ID 705) cvd_indicator_metric_area_breakdown( metric_id = 128, time_period_id = 17, area_id = 705 ) |> dplyr::select(SystemLevelName, AreaID, AreaName, Value)# Compare performance for metric ID 128 in time period 17 for # Salford South East PCN (area ID 705) cvd_indicator_metric_area_breakdown( metric_id = 128, time_period_id = 17, area_id = 705 ) |> dplyr::select(SystemLevelName, AreaID, AreaName, Value)
Returns detailed area data for a single CVD metric (metric_id) for a specified NHS area (area_id) and reporting period (time_period_id) from the CVDPREVENT API. This function provides all values and breakdowns available for the selected metric within the chosen context, allowing analysis and visualisation of precise, granular results (e.g., age groups, sexes, ethnicities).
cvd_indicator_metric_data(metric_id, time_period_id, area_id)cvd_indicator_metric_data(metric_id, time_period_id, area_id)
metric_id |
Integer (required). The MetricID for which to retrieve values. Use |
time_period_id |
Integer (required). The reporting period (time period) for which to return metric data. Use |
area_id |
Integer (required). The AreaID for which to return metric data. Use |
Use this function to retrieve all available breakdowns for a metric in a specific area and period, such as for in-depth local reporting, dashboard figures, or subgroup analysis. It is best used when you know the exact metric required for your query.
A named list containing three tibbles:
Tibble. Metadata and definitions for the selected metric.
Tibble. Metric values for the specified NHS area (area_id).
Tibble. Metric values for England, used for benchmarking and comparison.
If no indicator data is found, returns a tibble describing the error.
indicator_metrics contains the following items:
Character. Symbol used to represent the metric axis (e.g., "%").
Character. Display format for the metric (e.g., "Proportion %").
Character. Unique code for the indicator (e.g., "CVDP002AF").
Integer. Internal ID for the indicator's format type.
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Display order for the indicator in dashboards or reports.
Character. Abbreviated name of the indicator for display.
Integer. Count of notifications associated with the indicator. Often zero.
Integer. ID of the reporting time period.
Character. Label for the reporting time period (e.g., "To March 2024").
Character. Subgroup label (e.g., "Male", "Female", "Persons").
Integer. Unique ID for the metric category.
Character. Name of the subgroup or category (e.g., "18–39", "Sex").
Integer. Display order for the metric category.
Character. Type of subgroup (e.g., "Age group", "Sex").
Integer. Unique ID for the specific metric being measured.
area_data and national_data contain the following items:
Integer. Unique identifier for the metric being measured.
Character. Type of subgroup (e.g., "Sex", "Age group").
Character. Name of the subgroup (e.g., "Female", "18–39").
Character. Label used to group individuals (e.g., "Male", "Persons").
Character. ONS code for the NHS area (e.g., "U60176").
Integer. Internal ID for the NHS area.
Character. Name of the NHS area (e.g., "3 Centres PCN").
Integer. Total number of individuals in the subgroup.
Integer. Unique identifier for the data record.
Numeric. Population or count used as the denominator in metric calculation.
Numeric. Scaling factor applied to the metric, if applicable. Often NA.
Character. Notification priority level, if available. Often NA.
Numeric. Lower bound of the confidence interval for the metric value.
Numeric. Maximum observed value for the metric across comparable areas.
Numeric. Median value for the metric across comparable areas.
Numeric. Minimum observed value for the metric across comparable areas.
Integer. Count of notifications associated with the indicator. Often zero.
Numeric. Count used as the numerator in metric calculation.
Numeric. 20th percentile value across comparable areas.
Numeric. 40th percentile value across comparable areas.
Numeric. 60th percentile value across comparable areas.
Numeric. 80th percentile value across comparable areas.
Integer. ID of the reporting time period.
Character. Label for the reporting time period (e.g., "To March 2024").
Numeric. Upper bound of the confidence interval for the metric value.
Numeric. Calculated metric value (e.g., percentage of patients treated).
Character. Additional notes or flags about the value. Often NA.
See the CVDPREVENT API documentation: Indicator metric data
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_metric_list(), cvd_indicator(), cvd_indicator_tags(), cvd_indicator_details(), cvd_indicator_sibling(), cvd_indicator_child_data(), cvd_indicator_data(), cvd_indicator_raw_data(), cvd_indicator_nationalarea_metric_data(), cvd_indicator_priority_groups(), cvd_indicator_pathway_group(), cvd_indicator_group(), cvd_indicator_metric_timeseries(), cvd_indicator_person_timeseries(), cvd_indicator_metric_systemlevel_comparison(), cvd_indicator_metric_area_breakdown()
# Retrieve a single metric breakdown showing how men aged 40-59 years # are treated with anticoagulants (MetricID = 126) for 3 Centres PCN # (AreaID = 1103) to March 2020 (TimePeriodID = 1) returned_list <- cvd_indicator_metric_data( time_period_id = 1, area_id = 1103, metric_id = 126 ) # See the structure of this data returned_list |> dplyr::glimpse() # See the definition for this metric returned_list$metrics |> dplyr::glimpse() # Compare performance between our area and the national average dplyr::bind_rows( returned_list$area_data, returned_list$national_data ) |> dplyr::glimpse()# Retrieve a single metric breakdown showing how men aged 40-59 years # are treated with anticoagulants (MetricID = 126) for 3 Centres PCN # (AreaID = 1103) to March 2020 (TimePeriodID = 1) returned_list <- cvd_indicator_metric_data( time_period_id = 1, area_id = 1103, metric_id = 126 ) # See the structure of this data returned_list |> dplyr::glimpse() # See the definition for this metric returned_list$metrics |> dplyr::glimpse() # Compare performance between our area and the national average dplyr::bind_rows( returned_list$area_data, returned_list$national_data ) |> dplyr::glimpse()
Retrieves all CVD indicators available for a given reporting period and given system level from the CVDPREVENT API, with an expanded view that includes 'MetricList' array for each indicator. This allows you to see not only which indicators are available, but also the specific metrics (e.g., breakdowns by age, sex or other attributes) associated with each indicator in the selected context.
Only indicators with available data for the specified time period and system level are returned. This function is useful for determining what granular metric breakdowns are provided for each indicator.
cvd_indicator_metric_list(time_period_id, system_level_id)cvd_indicator_metric_list(time_period_id, system_level_id)
time_period_id |
Integer (required). The reporting period (time period) for which to return indicators and metrics. use |
system_level_id |
Integer (required). The system level (e.g., National, Region, ICB, PCN, Practice) for which to return indicators and metrics. Use |
Use this function to explore the detailed metric breakdowns available for each indicator before performing data extraction or analysis. The MetricList column is unnested for convenience, so each row represents a single metric linked to an indicator.
A tibble containing one row for each indicator-metric pair avialable for the specified system level and time period. Columns typically include:
Character. Symbol used to represent the metric axis (e.g., "%").
Character. Display format for the metric (e.g., "Proportion %").
Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
Character. Unique code for the indicator (e.g., "CVDP002SMOK").
Integer. Internal ID for the indicator's format type.
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Display order for the indicator in dashboards or reports.
Character. Abbreviated name of the indicator for display purposes.
Integer. Count of notifications associated with the indicator.
Character. Label used to group individuals (e.g., "Male", "Persons").
Character. Name of the subgroup or category (e.g., "40–59", "Mixed").
Character. Type of subgroup (e.g., "Age group", "Sex", "Ethnicity").
Integer. Unique identifier for the specific metric being measured.
If no indicators or metrics are found returns a tibble describing the error.
See the CVDPREVENT API documentation: Indicator metric list
This function may take longer than 5 seconds to complete due to API response time.
# List metrics for the prevalence of atrial fibrillation (indicator ID 1), # focusing on metrics for the 40-59 years age group at the national level: cvd_indicator_metric_list(time_period_id = 17, system_level_id = 1) |> dplyr::filter(IndicatorID == 1, MetricCategoryName == "40-59") |> dplyr::count(IndicatorID, IndicatorShortName, MetricID, MetricCategoryName, CategoryAttribute) |> dplyr::select(-n) # Get all indicator-metric pairs for GP practice level (system level 5) in a given period cvd_indicator_metric_list(time_period_id = 17, system_level_id = 5)# List metrics for the prevalence of atrial fibrillation (indicator ID 1), # focusing on metrics for the 40-59 years age group at the national level: cvd_indicator_metric_list(time_period_id = 17, system_level_id = 1) |> dplyr::filter(IndicatorID == 1, MetricCategoryName == "40-59") |> dplyr::count(IndicatorID, IndicatorShortName, MetricID, MetricCategoryName, CategoryAttribute) |> dplyr::select(-n) # Get all indicator-metric pairs for GP practice level (system level 5) in a given period cvd_indicator_metric_list(time_period_id = 17, system_level_id = 5)
Returns a tibble comparing the performance of a specified metric across all areas within the same system level (e.g., all PCNs within an ICB) for a given time period. This function powers the System Level Comparison chart in CVDPREVENT reporting.
cvd_indicator_metric_systemlevel_comparison(metric_id, time_period_id, area_id)cvd_indicator_metric_systemlevel_comparison(metric_id, time_period_id, area_id)
metric_id |
Integer (required). The ID of the metric to compare. Use |
time_period_id |
Integer (required). The ID of the reporting period. Use |
area_id |
Integer (required). The ID of the NHS area to anchor the comparison. Use |
The output includes:
Metric values for the selected area and its system-level peers
Target thresholds (if defined)
System-level metadata (e.g., "PCN", "ICB")
This function is useful for:
Benchmarking local performance against peer organisations
Identifying variation across system-level areas
Supporting equity and improvement initiatives at regional levels
To find valid metric_id values, use cvd_indicator_metric_list() or cvd_indicator_data().
For valid area_id values, use cvd_area_list() or cvd_area_search().
For valid time_period_id values, use cvd_time_period_list().
A tibble where each row represents an NHS area within the same system level, showing its performance for a specified metric. Columns include:
Character. Indicates whether the row represents national-level data ("Y" or "N").
Integer. Identifier for the system level (e.g., 4 = PCN).
Numeric. Median value for the metric across all areas in the system level.
Character. Name of the system level (e.g., "PCN").
Integer. Display order for the system level.
Character. Code for the NHS area (e.g., "U55387").
Integer. Unique identifier for the NHS area.
Character. Name of the NHS area (e.g., "Barking & Dagenham North PCN").
Numeric. Final calculated value for the metric in the area.
If no data is available for the given parameters, a tibble describing the error is returned.
See the CVDPREVENT API documentation: Indicator metric system level comparison
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_metric_list() to browse available metrics,
cvd_area_list() and cvd_area_search() to find valid area IDs,
cvd_time_period_list() to explore reporting periods,
cvd_indicator_metric_timeseries() for longitudinal analysis,
cvd_indicator_metric_area_breakdown() for localised comparisons,
cvd_indicator_priority_groups() for grouped indicator metadata
# Compare performance for metric ID 1270 in time period 17 for Salford South East PCN (area ID 705) cvd_indicator_metric_systemlevel_comparison( metric_id = 1270, time_period_id = 17, area_id = 705 ) |> dplyr::filter(AreaID %in% c(705:709), !is.na(Value)) |> dplyr::select(SystemLevelName, AreaID, AreaName, Value)# Compare performance for metric ID 1270 in time period 17 for Salford South East PCN (area ID 705) cvd_indicator_metric_systemlevel_comparison( metric_id = 1270, time_period_id = 17, area_id = 705 ) |> dplyr::filter(AreaID %in% c(705:709), !is.na(Value)) |> dplyr::select(SystemLevelName, AreaID, AreaName, Value)
Returns a tibble containing time series data for a specified metric and NHS area. The output includes both national-level (England) and local-level values across reporting periods, enabling direct comparison and trend analysis.
cvd_indicator_metric_timeseries(metric_id, area_id)cvd_indicator_metric_timeseries(metric_id, area_id)
metric_id |
Integer (required). The ID of the metric to retrieve. Use |
area_id |
Integer (required). The ID of the NHS area to retrieve data for. Use |
This function is designed to support longitudinal analysis of indicator performance. It returns:
Time series values for the selected metric in the specified area
Corresponding national values (AreaID = 1)
Target thresholds (if defined) for benchmarking
The result includes one row per time period per area, allowing users to:
Visualise trends over time
Compare local performance against national averages
Track progress toward clinical targets
To find valid metric_id values, use cvd_indicator_metric_list() or cvd_indicator_data().
For valid area_id values, use cvd_area_list() or cvd_area_search().
A tibble where each row represents a time period for a specific NHS area, including the observed metric value and associated target threshold. Columns include:
Character. Code for the NHS area (e.g., "U60510" for a PCN, "E92000001" for England).
Integer. Unique identifier for the NHS area.
Character. Name of the NHS area (e.g., "Salford South East PCN").
Integer. Number of records included in the calculation (e.g., eligible patients).
Numeric. Denominator used in the metric calculation.
Numeric. Scaling factor applied to the metric, if applicable. Often blank.
Numeric. Numerator used in the metric calculation.
Integer. Identifier for the reporting period.
Character. Display label for the time period (e.g., "To June 2024").
Numeric. Final calculated value for the metric in the given period.
Character. Descriptive label for the target threshold (e.g., "Upper threshold for QOF").
Numeric. Target value to be achieved (e.g., 95).
If no data is available for the given parameters, a tibble describing the error is returned.
See the CVDPREVENT API documentation: Indicator time series metrics
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_metric_list() to browse available metrics,
cvd_area_list() and cvd_area_search() to find valid area IDs,
cvd_indicator_data() to retrieve current metric values,
cvd_indicator_priority_groups() for grouped indicator metadata,
cvd_indicator_metric_area_breakdown() for area-level comparisons,
cvd_indicator_person_timeseries() for person-level time series data
# List data for Salford South East PCN (area ID 705) for 'AF: treatment with # anticoagulants' for women people aged 60-79 years (metric ID 130): cvd_indicator_metric_timeseries(metric_id = 130, area_id = 705) |> dplyr::select(AreaName, TimePeriodName, TimePeriodID, Value) |> tidyr::pivot_wider( names_from = AreaName, values_from = Value )# List data for Salford South East PCN (area ID 705) for 'AF: treatment with # anticoagulants' for women people aged 60-79 years (metric ID 130): cvd_indicator_metric_timeseries(metric_id = 130, area_id = 705) |> dplyr::select(AreaName, TimePeriodName, TimePeriodID, Value) |> tidyr::pivot_wider( names_from = AreaName, values_from = Value )
Returns a named list of tibbles containing: (1) metric data for the specified NHS area and the national (England, AreaID = 1) aggregate, and (2) details achieving the target value (if defined), including the target percentage and the additional number of patients needed to reach the target. This function supports benchmarking local performance vs. the national average, and helps quantify gaps to clinical targets.
If there is no data for either national or the chosen area for the given parameters, an error tibble is returned.
cvd_indicator_nationalarea_metric_data(time_period_id, area_id, metric_id)cvd_indicator_nationalarea_metric_data(time_period_id, area_id, metric_id)
time_period_id |
Integer (required). The reporting period (time period) for which to retrieve metric data. Use |
area_id |
Integer (required). The AreaID for which to retrieve data in addition to the national aggregate. use |
metric_id |
Integer (required). The MetricID for which to retrieve values. Use |
Use this function to benchmark a local area's metric value against the national figure and to understand the actual gap to a clinically meaningful target.
A named list with up to two tibbles:
Tibble with one or more rows, summarising the metric for the specified area and the England aggregate (AreaID = 1).
Tibble (if available) with target-setting details for the area
If no data exists for both the area and the national aggregate for the given parameters, returns a tibble describing the error.
area contains the following columns:
Character. Code for the NHS area (e.g., "U68943" for Chester South PCN, "E92000001" for England).
Integer. Unique identifier for the NHS area.
Character. Name of the NHS area (e.g., "Chester South PCN", "England").
Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
Character. Indicates whether the area represents national-level data ("Y" or "N").
Integer. Count of notifications associated with the area for the given metric.
Numeric. Final calculated value for the metric in the specified area.
target contains the following columns:
Character. Descriptive label for the target (e.g., "Upper threshold for QOF").
Integer. Number of additional patients needed to achieve the target threshold.
Numeric. Target value or threshold to be achieved (e.g., 95).
See the CVDPREVENT API documentation: Indicator national area metric data
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_metric_list(), cvd_indicator_metric_data(), cvd_indicator_data(), cvd_indicator_raw_data(), cvd_area_list()
# Compare performance against metric 150 (AF: treatment with anticoagulants # - all people) in 'Chester South PCN' (area ID 553) with national # performance: returned_list <- cvd_indicator_nationalarea_metric_data( metric_id = 150, time_period_id = 17, area_id = 553 ) # See what the list contains returned_list |> summary() # Extract the `area` details area_data <- returned_list$area area_data # Extract `target` details target_data <- returned_list$target target_data# Compare performance against metric 150 (AF: treatment with anticoagulants # - all people) in 'Chester South PCN' (area ID 553) with national # performance: returned_list <- cvd_indicator_nationalarea_metric_data( metric_id = 150, time_period_id = 17, area_id = 553 ) # See what the list contains returned_list |> summary() # Extract the `area` details area_data <- returned_list$area area_data # Extract `target` details target_data <- returned_list$target target_data
Returns a tibble of indicators associated with a single pathway group, identified by its ID. Pathway groups are thematic sub-groupings of priority groups and are visible in the Regional & ICS Insights page. This function enables users to retrieve all indicators linked to a specific pathway group (e.g., "Chronic Kidney Disease").
cvd_indicator_pathway_group(pathway_group_id)cvd_indicator_pathway_group(pathway_group_id)
pathway_group_id |
Integer (required). The ID of the pathway group to retrieve. Use |
A tibble containing indicators associated with the specified pathway group. Each row represents a single indicator and includes the following columns:
Integer. Unique identifier for the pathway group (e.g., 9 for "Chronic Kidney Disease").
Character. Name of the pathway group (e.g., "Chronic Kidney Disease").
Character. Symbol used to represent the metric axis (e.g., "%").
Character. Display format for the metric (e.g., "Proportion %").
Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
Character. Unique code for the indicator (e.g., "CVDP006CKD").
Integer. Internal ID for the indicator's format type.
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Unique identifier for the specific metric instance.
Integer. Count of notifications associated with the indicator.
Integer. Display order of the indicator within the pathway group.
Character. Thematic label for the indicator's clinical focus (e.g., "Diagnosis", "Monitoring", "Management").
If the request fails or the ID is invalid, a tibble with error details is returned instead.
See the CVDPREVENT API documentation: indicator pathway group
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_metric_list(), cvd_indicator(),
cvd_indicator_tags(), cvd_indicator_details(), cvd_indicator_sibling(),
cvd_indicator_child_data(), cvd_indicator_data(), cvd_indicator_metric_data(),
cvd_indicator_raw_data(), cvd_indicator_nationalarea_metric_data(),
cvd_indicator_priority_groups(), cvd_indicator_group(),
cvd_indicator_metric_timeseries(), cvd_indicator_person_timeseries(),
cvd_indicator_metric_systemlevel_comparison(), cvd_indicator_metric_area_breakdown()
# Return indicators for the 'Chronic Kidney Disease' Pathway Group (ID 9): cvd_indicator_pathway_group(pathway_group_id = 9) |> dplyr::select( PathwayGroupName, PathwayGroupID, IndicatorCode, IndicatorID, IndicatorName )# Return indicators for the 'Chronic Kidney Disease' Pathway Group (ID 9): cvd_indicator_pathway_group(pathway_group_id = 9) |> dplyr::select( PathwayGroupName, PathwayGroupID, IndicatorCode, IndicatorID, IndicatorName )
Returns a tibble containing time series data for a specified indicator and NHS area, broken down by inequality markers such as age group, ethnicity, deprivation quintile, and sex. This function supports the Inequalities Markers Time Series chart used in CVDPREVENT reporting.
cvd_indicator_person_timeseries(indicator_id, area_id)cvd_indicator_person_timeseries(indicator_id, area_id)
indicator_id |
Integer (required). The ID of the indicator to retrieve. Use |
area_id |
Integer (required). The ID of the NHS area to retrieve data for. Use |
The output includes:
Time series values for each subgroup within the selected indicator
Target thresholds (if defined) for benchmarking
Metric category metadata (e.g., "Age group", "Ethnicity")
This function is useful for:
Analysing disparities in indicator performance across population subgroups
Tracking progress toward clinical targets over time
Supporting equity-focused reporting and visualisation
To find valid indicator_id values, use cvd_indicator_list() or cvd_indicator_priority_groups().
For valid area_id values, use cvd_area_list() or cvd_area_search().
A tibble where each row represents a time period for a specific NHS area and inequality subgroup. Columns include:
Character. Code for the NHS area (e.g., "U60510" for a PCN).
Integer. Unique identifier for the NHS area.
Character. Name of the NHS area (e.g., "Salford South East PCN").
Integer. Unique identifier for the subgroup category (e.g., age band, ethnicity).
Character. Label for the subgroup (e.g., "Female", "80+", "White").
Integer. Identifier for the reporting period.
Character. Display label for the time period (e.g., "To March 2025").
Numeric. Final calculated value for the metric in the given subgroup and time period. May be blank if unavailable.
Integer. Identifier for the type of inequality marker (e.g., 1 = Age group, 3 = Ethnicity).
Character. Descriptive name of the inequality marker type (e.g., "Sex", "Age group", "Ethnicity").
Character. Descriptive label for the target threshold (e.g., "Upper threshold for QOF").
Numeric. Target value to be achieved (e.g., 95).
If no data is available for the given parameters, a tibble describing the error is returned.
See the CVDPREVENT API documentation: Indicator person time series
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list() to browse indicators,
cvd_indicator_priority_groups() to explore indicator groupings,
cvd_area_list() and cvd_area_search() to find valid area IDs,
cvd_indicator_metric_timeseries() for overall time series data,
cvd_indicator_metric_area_breakdown() for area-level comparisons
# View age group inequalities for indicator ID 7 in Salford South East PCN (area ID 705) cvd_indicator_person_timeseries(indicator_id = 7, area_id = 705) |> dplyr::filter( MetricCategoryTypeName == "Age group", !is.na(Value) ) |> dplyr::select(MetricCategoryName, TimePeriodName, TimePeriodID, Value) |> tidyr::pivot_wider( names_from = MetricCategoryName, values_from = Value )# View age group inequalities for indicator ID 7 in Salford South East PCN (area ID 705) cvd_indicator_person_timeseries(indicator_id = 7, area_id = 705) |> dplyr::filter( MetricCategoryTypeName == "Age group", !is.na(Value) ) |> dplyr::select(MetricCategoryName, TimePeriodName, TimePeriodID, Value) |> tidyr::pivot_wider( names_from = MetricCategoryName, values_from = Value )
Retrieves a tibble of indicator priority groups from the CVDPREVENT API. Priority groups reflect high-level clinical, operational or policy themes (such as "Inequalities" or "NHS Long Term Plan") and provide a way to cluster or filter multiple indicators for reporting and analytics.
cvd_indicator_priority_groups()cvd_indicator_priority_groups()
Use this function to provide grouping / filtering options for dashboards or reports, or to explore which indicator themes are tracked in CVDPREVENT. Typically, you will select the priority group's name and ID for grouping or filtering tasks.
A tibble with one row per indicator / priority group containing the following columns:
Character. High-level grouping label for the indicator (e.g., "CKD", "Prevalence", "ABC").
Character. Symbol used to represent the metric axis (e.g., "%").
Character. Display format for the metric (e.g., "Proportion %", "Rate per 10,000 patients").
Character. Notification priority level, if applicable (e.g., "Blue"). Often blank.
Character. Unique code for the indicator (e.g., "CVDP002AF").
Integer. Internal ID for the indicator's format type.
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Unique identifier for the specific metric instance.
Integer. Count of notifications associated with the indicator.
Integer. Unique identifier for the clinical pathway group.
Character. Name of the clinical pathway group (e.g., "Chronic Kidney Disease", "Hypertension").
Integer. Display order for the priority group within its pathway.
Integer. Unique identifier for the priority group.
Character. Thematic label for the indicator's clinical focus (e.g., "Diagnosis", "Management", "Monitoring").
If no priority groups are found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Indicator priority groups
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_group(), cvd_area_list(), cvd_time_period_list()
# List all available priority group display names and their IDs cvd_indicator_priority_groups() |> dplyr::select(PriorityGroupID, PriorityGroup) # Preview group names for a sidebar filter in a dashboard groups <- cvd_indicator_priority_groups() unique(groups$PriorityGroup)# List all available priority group display names and their IDs cvd_indicator_priority_groups() |> dplyr::select(PriorityGroupID, PriorityGroup) # Preview group names for a sidebar filter in a dashboard groups <- cvd_indicator_priority_groups() unique(groups$PriorityGroup)
Returns raw values for multiple metrics within an indicator (specified as indicator_id) for a single NHS system level and reporting period using the CVDPREVENT API. This function fetches unfiltered raw data at the metric level, allowing comprehensive extraction for all selected metrics and their available breakdowns (such as by age, sex or other category) within the chosen context.
cvd_indicator_raw_data(time_period_id, system_level_id, indicator_id)cvd_indicator_raw_data(time_period_id, system_level_id, indicator_id)
time_period_id |
Integer (required). The reporting period (time period) for which to retrieve data. Use |
system_level_id |
Integer (required). The SystemLevelID for which to retrieve data. Use |
indicator_id |
Integer vector (required). One or more IndicatorIDs specifying which indicator and its associated metrics to return. Use |
Use this function to retrieve a wide set of metric breakdowns for a given indicator in a single area and time period - useful for broad data extractions, dashboards or advanced analytics.
A tibble with one row per metric breakdown for all requested metrics. The tibble has the following columns:
Character. ONS geographic code for the area (e.g., "E92000001" for England).
Character. Name of the geographic area.
Character. Subgroup label (e.g., "Male", "Female", "Persons").
Numeric. Population or count used as the denominator in metric calculation.
Numeric. Scaling factor applied to the metric, if applicable. May be NA.
Character. Notification priority level, if available. Often NA.
Character. Unique code for the indicator (e.g., "CVDP002AF").
Character. Full descriptive name of the indicator.
Character. Abbreviated name of the indicator.
Numeric. Lower bound of the confidence interval for the metric value.
Character. Name of the subgroup or category (e.g., "40–59", "Female").
Character. Type of subgroup (e.g., "Age group", "Sex", "Ethnicity").
Integer. Count of notifications associated with the indicator. Often zero.
Numeric. Count used as the numerator in metric calculation.
Character. Label for the time period (e.g., "To December 2024").
Numeric. Upper bound of the confidence interval for the metric value.
Numeric. Calculated metric value (e.g., percentage of patients treated).
Character. Additional notes or flags about the value. Often NA.
See the CVDPREVENT API documentation: Indicator raw data
This function may take longer than 5 seconds to complete due to API response time.
# Retrieve metric data for 'CVD: All-cause mortality' (IndicatorID = 35) across # NHS Regions (SystemLevelID = 6) in the period April 2024 to # March 2025 (TimePeriodID = 27) and view a sample of 4 rows: cvd_indicator_raw_data( time_period_id = 27, system_level_id = 6, indicator_id = 35 ) |> dplyr::slice_sample(n = 4) # Find a valid indicator IDs for a specified time period and system level, # then retrieve raw data for one of these indicators <- cvd_indicator_list(time_period_id = 22, system_level_id = 4) cvd_indicator_raw_data( time_period_id = 22, system_level_id = 4, indicator_id = indicators$IndicatorID[1] )# Retrieve metric data for 'CVD: All-cause mortality' (IndicatorID = 35) across # NHS Regions (SystemLevelID = 6) in the period April 2024 to # March 2025 (TimePeriodID = 27) and view a sample of 4 rows: cvd_indicator_raw_data( time_period_id = 27, system_level_id = 6, indicator_id = 35 ) |> dplyr::slice_sample(n = 4) # Find a valid indicator IDs for a specified time period and system level, # then retrieve raw data for one of these indicators <- cvd_indicator_list(time_period_id = 22, system_level_id = 4) cvd_indicator_raw_data( time_period_id = 22, system_level_id = 4, indicator_id = indicators$IndicatorID[1] )
Returns data for all sibling areas (i.e., areas sharing the same parent) and the specified area itself, for a given metric and reporting period from the CVDPREVENT API. This endpoint is intended to provide a direct comparison of a single metric across related areas (e.g., all PCNs within an ICB, or all practices within a PCN).
Only the selected metric is returned for each sibling area.
cvd_indicator_sibling(time_period_id, area_id, metric_id)cvd_indicator_sibling(time_period_id, area_id, metric_id)
time_period_id |
Integer (required). The reporting period (time period) for which to return sibling data. Use |
area_id |
Integer (required). The AreaID for which sibling data will be determined. Use |
metric_id |
Integer (required). The MetricID for which to return data. Use |
Use this function to compare a metric across all areas at the same hierarchical level (e.g., compare all practices in a PCN or all PCNs in an ICB) for benchmarking and visualisation purposes.
A tibble containing the data for the specified metric in the selected area and all its siblings for the given reporting period. Columns include:
Character. Grouping label used to define the population subset (e.g., "Male").
Character. Unique code for the indicator (e.g., "CVDP002AF").
Integer. Unique identifier for the indicator.
Character. Full descriptive name of the indicator.
Integer. Display order for the indicator in dashboards or reports.
Character. Abbreviated name of the indicator for display purposes.
Integer. Unique identifier for the metric category.
Character. Name of the subgroup or category (e.g., "40–59").
Integer. Display order for the category within its type.
Character. Type of category used for breakdown (e.g., "Age group").
Character. Code for the NHS area (e.g., PCN).
Integer. Unique identifier for the NHS area.
Character. Name of the NHS area (e.g., "Greenwood PCN").
Integer. Number of records included in the calculation.
Integer. Unique identifier for the data point.
Numeric. Denominator used in the metric calculation.
Numeric. Scaling factor applied to the metric, if applicable. Often blank.
Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
Numeric. Lower bound of the confidence interval.
Numeric. Maximum observed value for the metric.
Numeric. Median value for the metric.
Numeric. Minimum observed value for the metric.
Integer. Count of notifications associated with the indicator.
Numeric. Numerator used in the metric calculation.
Numeric. 20th percentile value.
Numeric. 40th percentile value.
Numeric. 60th percentile value.
Numeric. 80th percentile value.
Integer. Identifier for the system level (e.g., 4 = PCN).
Character. Name of the system level (e.g., "PCN").
Integer. Identifier for the time period associated with the metric.
Character. Display label for the time period (e.g., "To March 2024").
Numeric. Upper bound of the confidence interval.
Numeric. Final calculated value for the metric.
Character. Notes or flags associated with the value (e.g., suppression warnings).
If no sibling data is found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Indicator sibling data
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_metric_list(), cvd_indicator(), cvd_indicator_tags(), cvd_indicator_details(), cvd_indicator_child_data(), cvd_indicator_data(), cvd_indicator_metric_data(), cvd_indicator_raw_data(), cvd_indicator_nationalarea_metric_data(), cvd_indicator_priority_groups(), cvd_indicator_pathway_group(), cvd_indicator_group(), cvd_indicator_metric_timeseries(), cvd_indicator_person_timeseries(), cvd_indicator_metric_systemlevel_comparison(), cvd_indicator_metric_area_breakdown()
# Compare the value of metric 126 for area 1103 and all its siblings in time period 17 cvd_indicator_sibling(time_period_id = 17, area_id = 1103, metric_id = 126) |> dplyr::select(AreaID, AreaName, Value, LowerConfidenceLimit, UpperConfidenceLimit) # Find a valid metric ID for an indicator, then get sibling data metrics <- cvd_indicator_metric_list(time_period_id = 17, system_level_id = 5) metric_id <- metrics$MetricID[1] cvd_indicator_sibling(time_period_id = 17, area_id = 1103, metric_id = metric_id)# Compare the value of metric 126 for area 1103 and all its siblings in time period 17 cvd_indicator_sibling(time_period_id = 17, area_id = 1103, metric_id = 126) |> dplyr::select(AreaID, AreaName, Value, LowerConfidenceLimit, UpperConfidenceLimit) # Find a valid metric ID for an indicator, then get sibling data metrics <- cvd_indicator_metric_list(time_period_id = 17, system_level_id = 5) metric_id <- metrics$MetricID[1] cvd_indicator_sibling(time_period_id = 17, area_id = 1103, metric_id = metric_id)
Retrieves a list of all tags from the CVDPREVENT API that can be used to filter indicators. Tags provide a way to categorise and search for indicators by clinical or reporting groupings (such as "Priority Group", "Pathway Group" or other clinical categories).
Use this function to obtain valid tag IDs for use in functions that support filtering by tag, such as cvd_indicator().
cvd_indicator_tags()cvd_indicator_tags()
Tags are useful for grouping or filtering indicators in dashboards, reports or scripted analyses. Tag IDs returned by this function can be supplied to functions like cvd_indicator() via the tag_id argument for targeted queries.
A tibble with one row per available indicator tag, containing the following colunns:
Integer. Unique identifier for the tag associated with an indicator.
Character. Descriptive label categorising the indicator (e.g., "monitoring", "prevention", "smoking").
If no tags are found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Indicator tags
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_list(), cvd_indicator_metric_list(), cvd_indicator(), cvd_indicator_details(), cvd_indicator_sibling(), cvd_indicator_child_data(), cvd_indicator_data(), cvd_indicator_metric_data(), cvd_indicator_raw_data(), cvd_indicator_nationalarea_metric_data(), cvd_indicator_priority_groups(), cvd_indicator_pathway_group(), cvd_indicator_group(), cvd_indicator_metric_timeseries(), cvd_indicator_person_timeseries(), cvd_indicator_metric_systemlevel_comparison(), cvd_indicator_metric_area_breakdown()
# List the first five indicator tags cvd_indicator_tags() |> dplyr::arrange(IndicatorTagID) |> dplyr::slice_head(n = 5) # Use a tag ID to filter indicators in another query tags <- cvd_indicator_tags() tag_id <- tags$IndicatorTagID[1] cvd_indicator(time_period_id = 17, area_id = 3, tag_id = tag_id)# List the first five indicator tags cvd_indicator_tags() |> dplyr::arrange(IndicatorTagID) |> dplyr::slice_head(n = 5) # Use a tag ID to filter indicators in another query tags <- cvd_indicator_tags() tag_id <- tags$IndicatorTagID[1] cvd_indicator(time_period_id = 17, area_id = 3, tag_id = tag_id)
Returns a tibble of indicator type IDs and their corresponding names, used to categorise CVD indicators in the CVDPREVENT API. This function is primarily a helper for cvd_time_period_list(), which accepts indicator_type_id as an optional parameter.
cvd_indicator_types()cvd_indicator_types()
A tibble of indicator types with the following columns:
Integer. Unique identifier for the indicator type.
Character. Name of the indicator type (e.g., "Standard", "Outcomes").
This function may take longer than 5 seconds to complete due to API response time.
# NB, the following example is not tested because it takes longer than # expected to return the results # List available indicator types cvd_indicator_types()# NB, the following example is not tested because it takes longer than # expected to return the results # List available indicator types cvd_indicator_types()
Retrieves all available reporting periods from the CVDPREVENT API. Optionally, you can filter periods by a specific indicator type (e.g., standard, outcome) using the indicator_type_id parameter.
cvd_time_period_list(indicator_type_id = NULL)cvd_time_period_list(indicator_type_id = NULL)
indicator_type_id |
Optional integer. If provided, restricts the returned time periods to those containing data of the given indicator type. |
This function is often used to determine valid values for time period parameters in other API queries. It is a building block for most higher-level data retrieval functions in this package.
A tibble containing details of available time periods with the following columns:
POSIXct. End date of the reporting period (e.g., "2025-06-30").
Integer. Unique identifier for the indicator type (e.g., 1 = Standard, 2 = Outcomes).
Character. Descriptive name of the indicator type (e.g., "Standard", "Outcomes").
POSIXct. Start date of the reporting period. Typically set to a default baseline (e.g., "1900-01-01").
Integer. Unique identifier for the time period.
Character. Display label for the time period (e.g., "To June 2025", "Apr 2024 – Mar 2025").
If no data is found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Time period for endpoint details.
This function may take longer than 5 seconds to complete due to API response time.
cvd_indicator_types(), cvd_time_period_system_levels()
# NB, the following examples are not tested because they take longer than # expected to return the results # List all available time periods cvd_time_period_list() # List time periods with data for a specific indicator type (e.g., Standard) cvd_time_period_list(indicator_type_id = 1)# NB, the following examples are not tested because they take longer than # expected to return the results # List all available time periods cvd_time_period_list() # List time periods with data for a specific indicator type (e.g., Standard) cvd_time_period_list(indicator_type_id = 1)
Retrieves all available reporting periods from the CVDPREVENT API, along with the NHS system levels included in each time period.
This function is useful to determine which system levels (e.g., national, region, ICB, PCN, practice) have data available for each reporting period.
cvd_time_period_system_levels()cvd_time_period_system_levels()
This function is helpful for understanding the data structure of each reporting period, especially if you need to filter or subset data by system level and time period in downstream API calls.
A tibble containing time periods and the corresponding system levels with the following columns:
A tibble with the following columns:
POSIXct. End date of the reporting period (e.g., "2023-12-31").
POSIXct. Start date of the reporting period. Typically set to a default baseline (e.g., "1900-01-01").
Integer. Unique identifier for the time period.
Character. Display label for the time period (e.g., "To December 2023", "Apr 2022 – Mar 2023").
Logical or character. Indicates whether the time period is visible in the API or dashboard ("Y" or "N").
Logical or character. Indicates whether the data is available at the national level ("Y" or "N").
Integer. Unique identifier for the system level (e.g., 1 = England, 4 = PCN).
Character. Name of the system level (e.g., "England", "Region", "Sub-ICB", "PCN").
If no data is found, returns a tibble describing the error.
See the CVDPREVENT API documentation: Time period system levels for technical details.
This function may take longer than 5 seconds to complete due to API response time.
cvd_time_period_list(), cvd_area_system_level_time_periods()
# Retrieve all time periods and associated system levels periods_levels <- cvd_time_period_system_levels() # Show available system levels for the latest time period periods_levels |> dplyr::slice_max(order_by = TimePeriodID) |> dplyr::select(TimePeriodID, TimePeriodName, SystemLevelID, SystemLevelName)# Retrieve all time periods and associated system levels periods_levels <- cvd_time_period_system_levels() # Show available system levels for the latest time period periods_levels |> dplyr::slice_max(order_by = TimePeriodID) |> dplyr::select(TimePeriodID, TimePeriodName, SystemLevelID, SystemLevelName)