Getting Started

The khisr package seamlessly integrates with the Kenya Health Information System (KHIS) API from R, empowering researchers and public health professionals to easily access and analyze valuable health data. Built on the DHIS2 platform, khisr automates data retrieval, saving you time and effort compared to manual methods.


To ensure a secure and seamless experience, khisr operates by default in authenticated mode, enabling you to interact with KHIS as a recognized user. This means that before diving into KHIS data exploration, you’ll need to establish your credentials with the system.

Setting Your Credentials:

  1. Obtain your KHIS credentials: These typically consist of a username and password, which you can acquire through appropriate channels within the KHIS organization.

  2. Store your credentials securely: khisr provides a convenient mechanism for storing your credentials within your R environment. To learn how to set and manage your credentials effectively, please refer to the comprehensive guide at Set Your Credentials.

# Set the credentials using username and password
khis_cred(username = 'KHIS username', password = 'KHIS password')

# Set credentials using configuration path
khis_cred(config_path = 'path/to/secret.json')


KHIS uses metadata to define the structure and meaning of the data stored in the system. For more information see data dimensions

Metadata helpers

khisr provides a number of high level metadata helpers for obtaining details of the different types of metadata. There is a helper for each of the main metadata categories in DHIS2, in fact auto complete in the users R IDE will often make typing these very fast. This is the list of the numerous high level metadata helpers in khisr.

khisr function KHIS API Endpoint
get_categories() categories
get_category_combos() categoryCombos
get_category_option_combos() categoryOptionCombos
get_category_option_group_sets() categoryOptionGroupSets
get_category_option_groups() categoryOptionGroups
get_category_options() categoryOptions
get_data_element_group_sets() dataElementGroupSets
get_data_element_groups() dataElementGroups
get_data_elements() dataElements
get_data_sets() dataSets
get_indicator_group_sets() indicatorGroupSets
get_indicator_groups() indicatorGroups
get_indicators() indicators
get_option_group_sets() optionGroupSets
get_option_groups() optionGroups
get_option_sets() optionSets
get_options() options
get_organisation_unit_groupsets() organisationUnitGroupSets
get_organisation_unit_groups() organisationUnitGroups
get_organisation_units() organisationUnits
get_dimensions() dimensions
get_user_groups() userGroups
get_period_types() periodTypes

Metadata object filter

To filter the metadata there are several filter operations that can be applied to the returned list of metadata. The format of the filter itself is straight-forward and follows the pattern property:operator:value, where property is the property on the metadata you want to filter on, operator is the comparison operator you want to perform and value is the value to check against (not all operators require value).

KHIS Operator Infix Operator Description
eq %.eq% Equality
!eq %.~eq% Inequality
ieq %.ieq% Case insensitive string, match exact
ne Inequality
like %.Like% Case sensitive string, match anywhere
!like %.~Like% Case sensitive string, not match anywhere
$like %.^Like% Case sensitive string, match start
!$like %.~^Like% Case sensitive string, not match start
like$ %.Like$% Case sensitive string, match end
!like$ %.~Like$% Case sensitive string, not match end
ilike Case insensitive string, match anywhere
!ilike %.~like% Case insensitive string, not match anywhere
$ilike %.^like% Case insensitive string, match start
!$ilike %.~^like% Case insensitive string, not match start
ilike$$% Case insensitive string, match end
!ilike$ %.~like$% Case insensitive string, not match end
gt Greater than
ge Greater than or equal
lt Less than
le %.le% Less than or equal
token %.token% Match on multiple tokens in search property
!token %.~token% Not match on multiple tokens in search property
in Find objects matching 1 or more values
!in %.~in% Find objects not matching 1 or more values

Working with metadata filters

Basic usage of the metadata filter

# Retrieve organisation units by county (level 2)
county <- get_organisation_units(level %.eq% '2')

# Retrieve county by name (Mombasa)
county <- get_organisation_units(level %.eq% '2',
                                 name 'mombasa')

data_element_id <- c('cXe64Yk0QMY', 'XEX93uLsAm2')

# Retrieve data elements by ID using operator in
data_elements <- get_data_elements(id data_element_id)

# Retrieve data elements by filtering using dataElementGroups
data_elements <- get_data_elements( 'moh 705')

Data analytics

The analytics resource in DHIS2 empowers you to access and analyze aggregated data across various dimensions. To effectively leverage this resource, let’s explore the key functions and parameters involved:

Key Functions

Dimension (dx)

The dimension query parameter defines which dimensions should be included in the analytics query. Any number of dimensions can be specified. The dimension parameter should be repeated for each dimension to include in the query response. The query response can potentially contain aggregated values for all combinations of the specified dimension items. The fixed dimensions are the data element (dx) period (time) (pe) and organisation unit (ou) dimension. You can dynamically add dimensions through categories, data element group sets and organisation unit group sets.

Dimension ID Dimensions
dx Data elements, indicators, data set reporting rate metrics,
data element operands, program indicators, program data elements,
program attributes, validation rules
pe ISO periods and relative periods (see “date and period format”)
ou Organisation unit hierarchy
Organisation unit identifiers, keywords USER_ORGUNIT,
co Category option combo identifiers (use all to get all items)
ao Category option combo identifiers (use all to get all items)

Filter (filter)

The filter parameter defines which dimensions should be used as filters for the data retrieved in the analytics query. Any number of filters can be specified. The filter parameter should be repeated for each filter to use in the query. A filter differs from a dimension in that the filter dimensions will not be part of the query response content, and that the aggregated values in the response will be collapsed on the filter dimensions. In other words, the data in the response will be aggregated on the filter dimensions, but the filters will not be included as dimensions in the actual response.

Constructing Queries

# To include a list dimensions for data elements id, dataset ids
dx %.d% c('dimension-id-1', 'dimension-id-2')

pe %.d% 'LAST_YEAR'

ou %.d% 'USER_ORGUNIT'

# showing in the analytics
    dx %.d% c('siOyOiOJpI8', 'Lt0FqtnHraW', 'OoakJhWiyZp'),
    pe %.d% 'LAST_YEAR',
    ou %.d% c('qKzosKQPl6G')

# Using the startDate and endDate with organisation unit keyword 'USER_ORGUNIT'
    dx %.d% c('siOyOiOJpI8', 'Lt0FqtnHraW', 'OoakJhWiyZp'),
    ou %.d% 'USER_ORGUNIT',
    pe %.d% 'all',
    startDate = '2023-07-01',
    endDate = '2023-12-31'
# Filter by period
pe %.f% 'LAST_YEAR'

# Filter by organisation unit
ou %.f% 'USER_ORGUNIT'

# showing in the analytics. filter by organisation unit with id 'qKzosKQPl6G'
# and period 'LAST_YEAR'
    dx %.d% c('siOyOiOJpI8', 'Lt0FqtnHraW', 'OoakJhWiyZp'),
    pe %.f% 'LAST_YEAR',
    ou %.f% 'qKzosKQPl6G'