API Structure: Locators / Organization Units near me

This endpoint retrieves a list of organization units in proximity to the provided geographic coordinates.

URL : api/v2/locator

Method: GET / POST

Authorization: Managed via Spring Framework Security (See: Link)

Note:

For PSI implementation, authorization is handled by OpenHIM, and Spring Boot security is disabled by default.

Request Parameters

Required Parameters

You must provide at least one of the following parameters

Parameter	dhis2 Attribute	Description
coordinates		(String) User's location in the format of Latitude, Longitude. This is used to find nearby organization units. Format: "latitude,longitude"
points		(Array of Decimals) An array of coordinates. Available only for the POST method.
latitude		(Decimal) Latitude component of the user's location.
longitude		(Decimal) Longitude component of the user's location.
Either of the above attributes is required
Organization Unit
uid	CORE \| OrgUnit UID	(String) Unique identifier (UID) generated by DHIS2 for an organization unit.
code	CORE \| Org Unit Code	(String) Code assigned to the organization unit.
shortName	CORE \| Org Unit shortName	(String) Short name of the organization unit.
Ancestor (Organization Unit)
ancestor.uid	CORE \| OrgUnit UID for ancestor	(String) OrgUnit UID / code for ancestor. When provided, all locators/facilities under it are populated. Represents the DHIS2 parent just above the Organization Unit.
ancestor.code	CORE \| OrgUnit code for ancestor

Optional parameters

Parameter	Option Value	Default Option	Description
paging	Boolean	true	Specifies whether pagination is required.
page	Number	1	Determines the page number to be returned.
pageSize	Number	10	Sets the total number of items per page.
distance	Number	10	Specifies the radius (in unit specified) within which to generate the organization units.
unit	Options: m (meters), km (kilometers), mi (miles)	km	Defines the unit of measurement for distance.
level	Number	7	Indicates the hierarchy level of the organization unit.
phoneNumber	Text (Phone Number)	N/A	DHIS2 core element that defines the phone number of the location.
DHIS2 custom ou attribute
type	Text		Specifies the type of the location.
tags	Text (Separated by ',' or '\|')	N/A	Defines the tags the locations are associated with. Returns all the organization which has at least one of the tags provided.
tags	Text (separated by &)	NA	Returns all the organization which has all of the tags provided.
services	Text (Separated by ',' or '\|')	N/A	Defines the services offered by the locations. Returns all the organization which has at least one of the service provided.
services	Text (separated by &)		Returns all the organization which has all of the services provided.
area	Text	N/A	Defines the broader area where the location is situated.
subArea	Text	N/A	Specifies the subarea of the location.
whatsapp	Text (phone Number)	N/A	Indicates the WhatsApp number of the location.
facebook	Text or URL	N/A	Provides the Facebook URL for the location.
responseFhir	Boolean	No	Determines if the response should be in FHIR or DHIS2 format.

URL (for GET request):

https://{{host}}/api/v2/locator?paging=false&coordinates=lat,lng&distance=5&unit=km

Payload (for POST request):

{
  "paging": true,
  "page": 1,
  "pageSize": 10,
  "ancestor": {
    "id": "a23acb2452xyz",
    "code": "KE"
  },
  "organisationunit": {
    "id", "q13we2452wsd",
    "shortName": "Sub Hospital"
  },
  "coordinates": lat,lng,
  "points": [lat,lng],
  "distance": 5,
  "unit": "km",
  "level": 7,
  "phoneNumber": "180999093107",
  "area": "Managua",
  "subArea": "Ciudad Sandino",
  "type": "Public",
  "tags": "tag1,tag2",
  "services": "service1,service2",
  "whatsapp": "977984123145",
  "facebook": "https://fb.me/facility1",
  "latitude": lat,
  "longitude": lon,
  "responseFhir": false
}

Response (In DHIS2):

{
    "pager": {...}
    "organisationUnits": [
        {
            "id": "xkcEJARvo2O",
            "parentId": "15561086",
            "code": "KE-CODE-123",
            "name": "Facility Clinic (KE-CODE-123)",
            "shortName": "Facility Clinic",
            "description": null,
            "openingDate": "2023-02-11",
            "closedDate": null,
            "comment": null,
            "url": null,
            "contactPerson": null,
            "address": "street1, city, subarea, area",
            "email": "mymail@gmail.com",
            "phoneNumber": "+254541483334",
            "path": "",
            "level": "7",
            "area": "Nairobi",
            "subArea": "Starehe",
            "latitude": "-1.28575",
            "longitude": "39.81234",
            "geometry": "{\"type\":\"Point\",\"coordinates\":[39.81234,-1.28575]}",
            "distance": 0.0,
            "openingHours": "Mon-Fri,8:00,17:00;Sat,9:00,14:00;Public Holiday,9:00,14:00;Sun,Closed",
            "services": "CCS,CNT,ANC,STI,HVS,HVT",
            "locationType": "OUT",
            "type": "Public",
            "tags": "KEUNV",
            "fb": null,
            "whatsapp": null,
            "showContactInfo": "TLF"
        }
    ]
}

Note: The attributes sequence might be different from the sequence listed above.

Response (in FHIR):

{
  "pager": {
    "page": 1,
    "pageCount": 1,
    "total": 1,
    "pageSize": 1,
    "first": true,
    "last": true
  },
  "locations": [
    {
      "resourceType": "Location",
            "id": "d5AeP1W7nT",
            "identifier": [
                {
                    "system": "http://www.acme.org/identifiers/location",
                    "value": "US-FH-1235"
                },
                {
                    "system": "http://www.acme.org/identifiers/location",
                    "value": "/s7JFm0K2cN/8xqYb6V3gL/i4hDz9R1mE/a2XpM3G6rC/c9NlB7P8jY/u3RcT5L9vH/d5AeP1W7nT"
                }
            ],
            "name": "Riverside General Hospital (US-FH-1235)",
            "alias": [
                "Riverside General Hospital"
            ],
            "description": null,
            "status": "active",
            "mode": "instance",
            "address": {
                "street1": "123 Main Street",
                "street2": null,
                "city": "Any City",
                "state": "NY",
                "postalCode": 12345,
                "country": "United State"
            },
            "contact": {
                "telecom": [
                    {
                        "system": "phone",
                        "value": "+14722240000",
                        "use": null
                    }
                ]
            },
            "position": {
                "longitude": 30.7983,
                "latitude": -10.25
            },
            "hoursOfOperation": "Mon-Fri,8:00,17:00",
            "healthCareServices": "COV,STI"
        }
    }
  ]
}

You can also find the POSTMAN examples below:
1. DHIS2 Response: POSTMAN

FHIR Response: POSTMAN