Page Comparison

The LocatorAPI currently has three endpoints. The locator API can currently support querying:

Locators or OrgUnits near by
List of Areas in a country
List of subAreas within the country and the area

Locators near me

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

url URL : api/v1v2/locator

methodMethod: POST

authorization: will be provided by admin

Mandatory parameters - you must provide at least one fo the following parameters

...

Parameter

...

dhis2 attribute

...

description

...

coordinates

...

core Org Unit geometry

...

code

...

core Org Unit Code

...

uid-exact match

...

uid-parent

Optional parameters

...

Parameter

...

Default value, if not provided

...

number

...

limit

...

10

...

distance

...

calculation

...

100

...

unit

...

phone

...

core

...

tag

...

custom Org Unit attribut

...

services

payload: :

Code Block

language	json

{
  "number": 10,
  "distance": 5,
  "unit": "km",
  "coordinates": "lat,lng",
  "iso": "KE",  ---> Remove
  "services": "service1,service2",
  "uid": 'q13we2452wsd',
  "code": "CODE-123",
  "contraception": "iud,imp",
  "tags": "tag1,tag2",
  "type": "Public",
  "area": "Managua",
  "subArea": "Ciudad Sandino",
  "phonenumber": "180999093107",
  "wap": "977984123145",
  "facebook": "https://fb.me/facility1"
}

response:

...

language	json

...

Status

colour	Green
title	GET

/

Status

colour	Yellow
title	POST

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

Info

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

Example

coordinates

(String)
User's location in the format of Latitude, Longitude. This is used to find nearby organization units.

Format: "latitude,longitude"

coordinates=-0.1663,35.5924

points

(Array of Decimals)
An array of coordinates. Available only for the

Status

colour	Yellow
title	POST

method.

Code Block
{ "ancestor": { "id": 1234 }, "points": [-1.286389, 36.817223], "distance": 10, "unit": "KM" }

latitude

(Decimal)
Latitude component of the user's location.

latitude=-26.18

longitude

(Decimal)
Longitude component of the user's location.

longitude=28.31

Info
Please consider either using coordinates or latitude & longitude. Points parameter is only available for POST request.

Organization Unit

uid

Status

title	core

| OrgUnit UID

(String)

Unique identifier (UID) generated by DHIS2 for an organization unit.

code

Status

title	core

| Org Unit Code

(String)

Code assigned to the organization unit.

shortName

Status

title	core

| Org Unit shortName

(String)

Short name of the organization unit.

Ancestor (Organization Unit)

ancestor.uid

Status

title	core

| OrgUnit UID for ancestor

(String)

OrgUnit UID / code for ancestor. When provided, all locators/facilities under it are populated. Represents the DHIS2 parent that represents the country.

ancestor.code

Status

title	core

| OrgUnit code for ancestor

Info

Please Note

Either of these three category of filters is required to get the API response
Consider using OrganisationUnit filter if you are looking for specific Location / organisation unit
You can use Ancestor and coordinates / (lat,lng) to get locations within the specific country.

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.

Filters

type	Text		Specifies the type of the location.
phoneNumber	Text (Phone Number)	N/A	DHIS2 core element that defines the phone number 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

Status

colour	Green
title	GET

request):

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

Payload (for

Status

colour	Yellow
title	POST

request):

Code Block

language	json

{
  "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):

Code Block

language	json

{
    "pager": {...}
    "organisationUnits": [
        {
            "ouContraceptivesid": "IMP,OCP,IUD,INJ,STL,EMC""xkcEJARvo2O",
        }     ]
}

Areas in the country

Provides list of areas in the country.

url : api/v1/area

method: POST

authorization: will be provided by admin

payload:

Code Block

language	json

{"parentId": "15561086",
            "countrycode": "KE-CODE-123",
            "pageNoname": 1, "Facility Clinic (KE-CODE-123)",
      "pageSize": 5,     "facilityTypeshortName": "PublicFacility Clinic",
     "tags": "KEUNV" }

response:

Code Block

language	json

{     "responsedescription": null,
   {         "returnCodeopeningDate": "200",
     2023-02-11",
  "totaNosofPages": 10,         "areasclosedDate": [null,
            {
   "comment": null,
            "areaurl": "Baringo"null,

               "countrycontactPerson": "Kenya" null,
            "address": "street1, }city, subarea, area",
          {  "email": "mymail@gmail.com",
             "areaphoneNumber": "Bomet+254541483334",
   
            "countrypath": "Kenya",
            } "level": "7",
            {
 "area": "Nairobi",
              "areasubArea": "BungomaStarehe",

               "countrylatitude": "Kenya-1.28575",
            }"longitude": "39.81234",
            "geometry": {
   "{\"type\":\"Point\",\"coordinates\":[39.81234,-1.28575]}",
            "areadistance": "Busia",
   0.0,
            "countryopeningHours": "Kenya"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",
            "areatype": "Elgeyo MarakwetPublic",

               "countrytags": "Kenya"KEUNV",
            "fb": null,
        }    "whatsapp": null,
   ],         "linksshowContactInfo": "TLF"
  [      }
      ]
}

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

Response (in FHIR):

Code Block

language	json

{
  "pager": {
       "page": 1,
    "relpageCount": "self",
        1,
       "href": "/locator-dev/api/area?1=1&country=KE&pageNo=1&pageSize=5"
   "total": 1,
    "pageSize": 1,
    "first": true,
    "last": true
  },
  "locations": [
    {
   {   "resourceType": "Location",
            "relid": "nextd5AeP1W7nT",
   
            "hrefidentifier": "/locator-dev/api/area?1=1&country=KE&pageNo=2&pageSize=5"
[
           }     {
   ],         "totalNosOfRecords": 48,         "currentPageNosystem": "1http://www.acme.org/identifiers/location",

       "status": "Showing 5 Areas"     }
}

SubAreas in the country

Provides list of areas in the country.

url : api/v1/subArea

method: POST

authorization: will be provided by admin

payload:

Code Block
{ "countryvalue": "GT",US-FH-1235" "area": "Guatemala", "pageNo": 1, }, "pageSize": 5, "facilityType": "Public", "tags": "KEUNV" }

response:

Code Block

{{
          "response": {         "returnCodesystem": "200http://www.acme.org/identifiers/location",
          "totaNosofPages": 10,         "subAreasvalue": ["/s7JFm0K2cN/8xqYb6V3gL/i4hDz9R1mE/a2XpM3G6rC/c9NlB7P8jY/u3RcT5L9vH/d5AeP1W7nT"
            {    }
            "subArea": "Amatitlán",
   ],
            "areaname": "Guatemala",Riverside General Hospital (US-FH-1235)",
             "countryalias": "GT"
            },
   [
         {       "Riverside General Hospital"
       "subArea": "Antigua Guatemala",    ],
            "areadescription": "Guatemala",
   null,
            "countrystatus": "GTactive",
             }"mode": "instance",
            "address": {
                "subAreastreet1": "Fraijanes123 Main Street",
                "areastreet2": "Guatemala"null,
                "countrycity": "GTAny City",
            },    "state": "NY",
       {         "postalCode": 12345,
      "subArea": "Guatemala Zona 1",       "country": "United State"
       "area": "Guatemala",    },
            "countrycontact": "GT"{
             },   "telecom": [
        {            {
    "subArea": "Guatemala Zona 10",                 "areasystem": "Guatemalaphone",
                "country": "GT"             }
   "value": "+14722240000",
    ],         "links": [          "use": null
 {                 "rel": "self", }
               "href": "/locator-dev/api/subArea?1=1&country=GT&area=Guatemala&pageNo=1&pageSize=5" ]
            },
            "position": {
                "rellongitude": "next"30.7983,
                "hreflatitude": "/locator-dev/api/subArea?1=1&country=GT&area=Guatemala&pageNo=2&pageSize=5"-10.25
            }
    ,
   ],         "totalNosOfRecordshoursOfOperation": 48,"Mon-Fri,8:00,17:00",
            "currentPageNohealthCareServices": "1COV,STI",
        "status": "Showing 5 Areas"}
    }
  }]
}

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

FHIR Response: POSTMAN

Version	Old Version 2	New Version Current
Changes made by	Rodolfo Melia	Utsav Ashish Koju
Saved on	Feb 15, 2023	Dec 11, 2023

Versions Compared

Key

Locators near me

Request Parameters

Required Parameters

Please Note

Filters

Areas in the country

SubAreas in the country