Background

DHIS2 has provided PSI and other organisation use DHIS2 as their de facto Master List of Facilities. DHIS2 provides various API endpoints to conveniently perform numerous CRUD operation . They have been a building blocks for all the DHIS2 apps the community built. These endpoints are mostly complete, comprehensive and well documented. But it has some shortfalls too. We cannot still perform any filters based on user location or specific coordinates. We cannot fetch a nearest organization units, its either all or none.across Org Units. DHIS API has a comprehensive documentation.

When creating consumer services, PSI requires to list facilites based on the current location of the user - this means listing facilities that are closest to the provided Latitude and Longitude of the user. This search option is not present in DHIS2, at least in the reviewed versions (2.38, 2.39 and 2.40 dev version - reviewed in February 2023).

Introduction

Locator API is an add-on to the DHIS2. This API endpoint provides a new way to retrieve organization unit.

...

self-contained API that provides new ways to retrieve organisation unit, in particular:

1. request for closest org units based on a specific coordinates.

2. Developer can also request for ‘n' numbers of ounits within 'x’ radius surrounding the specific coordinates

3. Developer can also find a closest ounit that is of specific type or provide specific facility.

Github

LocatorAPI

Change log

...

1. , with the possibility to define a boundary as a ratio in Kms.

2. Return an enumeration of Custom Attributes values - implemented for Area and SubArea, two of the suggested custom attributes that we recommend to install as part of the Org Units.

3. Filtering by two or more Org Units custom attribute Github.