Versions Compared

Version Old Version 3 New Version Current
Changes made by

Rodolfo Melia

Utsav Ashish Koju

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

  1. Locators or OrgUnits near by

  2. List of Areas in a country

  3. 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

method: POST

authorization: will be provided by admin

Mandatory parameters - you Method:

Status
colourGreen
titleGET
/
Status
colourYellow
titlePOST

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 fo of the following parameters

Parameter

dhis2

attribute

description

coordinates

core Org Unit geometry

code

core Org Unit Code

uid-exact match

uid-parent

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
colourYellow
titlePOST
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
titlecore
| OrgUnit UID

(String)

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

code

Status
titlecore
| Org Unit Code

(String)

Code assigned to the organization unit.

shortName

Status
titlecore
| Org Unit shortName

(String)

Short name of the organization unit.

Ancestor (Organization Unit)

ancestor.uid

Status
titlecore
| 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
titlecore
| 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

Default value, if not provided

number

limit

10

distance

calculation

100

unit

phone

core

tag

custom Org Unit attribut

services

payload: :

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.

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.

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
colourGreen
titleGET
request):

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

Payload (for

Status
colourYellow
titlePOST
request):

Code Block
languagejson
{
  "numberpaging": 10true,
  "distancepage": 51,
  "unitpageSize": 10,
  "km",ancestor": {
    "coordinatesid": "lat,lnga23acb2452xyz",
    "isocode": "KE",
 ---> Remove },
  "servicesorganisationunit": {
    "id"service1,service2 "q13we2452wsd",
    "uidshortName": 'q13we2452wsd' "Sub Hospital"
  },
  "codecoordinates": "CODE-123",lat,lng,
  "points": [lat,lng],
  "contraceptiondistance": "iud5,imp",
  "tagsunit": "km"tag1,tag2"
  "level": 7,
  "typephoneNumber": "Public180999093107",
  "area": "Managua",
  "subArea": "Ciudad Sandino",
  "phonenumbertype": "Public",
  "tags": "tag1,tag2",
  "services": "180999093107service1,service2",
  "wapwhatsapp": "977984123145",
  "facebook": "https://fb.me/facility1",
  "latitude": lat,
  "longitude": lon,
  "responseFhir": false
}

responseResponse (In DHIS2):

Code Block
languagejson
{
    "pager": {...}
    "organisationUnits": [
        {
            "returnCodeid": "200xkcEJARvo2O",
    "outlet        "parentId": ["15561086",
             {"code": "KE-CODE-123",
            "dhisCodename": "Facility Clinic (KE-CODE-123)",
            "dhisId"shortName": "Facility Clinic",
            "description": null,
            "openingDate": "xkcEJARvo2O2023-02-11",
            "servicesStandard": "CCS,CNT,ANC,STI,HVS,HVT"closedDate": null,
            "comment": null,
            "url": null,
            "contactPerson": null,
            "address": "street1, city, subarea, area",
            "outletTypeemail": "Publicmymail@gmail.com",
            "ouShowContactInfophoneNumber": "TLF+254541483334",
            "path": "",
            "level": "7",
            "area": "Nairobi",
            "subArea": "Starehe",
            "latitude": "-1.28575",
            "outletName": "Facility Clinic""longitude": "39.81234",
            "geometry": "{\"type\":\"Point\",\"coordinates\":[39.81234,-1.28575]}",
            "distance": 0.0,
            "phoneNumberopeningHours": "+254541483334Mon-Fri,8:00,17:00;Sat,9:00,14:00;Public Holiday,9:00,14:00;Sun,Closed",
            "postgresIdservices": "1511345870CCS,CNT,ANC,STI,HVS,HVT",
            "locatorTypelocationType": "OUT",
            "locationtype": "Public",
  {          "tags": "KEUNV",
     "area": "Nairobi"       "fb": null,
            "whatsapp": null,
            "showContactInfo": "TLF"
        }
    ]
}

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

Response (in FHIR):

Code Block
languagejson
{
  "areaSubpager": "Starehe"{
    "page": 1,
    "pageCount": 1,
    "total": 1,
    "pageSize": 1,
    "addressfirst": "street1, city, subarea, areatrue,
    "last": true
  },
  "locations": [
    {
      "resourceType": "Location",
            "id": "d5AeP1W7nT",
            "identifier": [
                {
                    "system": "http://www.acme.org/identifiers/location",
                    "latitudevalue": "-1.28575",US-FH-1235"
                },
                {
                    "system": "http://www.acme.org/identifiers/location",
                    "longitudevalue": "39.81234/s7JFm0K2cN/8xqYb6V3gL/i4hDz9R1mE/a2XpM3G6rC/c9NlB7P8jY/u3RcT5L9vH/d5AeP1W7nT"
                }
            ],
            "dhisNamename": "FacilityRiverside General ClinicHospital (KEUS-CODEFH-1231235)",
            "openingHoursalias": [
                "Riverside General Hospital"
            ],
            "description": null,
            "status": "Mon-Fri,8:00,17:00;Sat,9:00,14:00;Public Holiday,9:00,14:00;Sun,Closed",active",
            "mode": "instance",
            "address": {
                "street1": "123 Main Street",
                "street2": null,
                "city": "Any City",
                "state": "NY",
                "postalCode": 12345,
                "country": "United State"
            },
            "contact": {
                "openingDate"telecom": [
                    {
                        "system": "2023-02-11phone",
            "ouTags            "value": "MSI+14722240000",
               "providers": []         "use": null
                    }
                ]
            },
            "ouContraceptives": "IMP,OCP,IUD,INJ,STL,EMCposition": {
                "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

  1. FHIR Response: POSTMAN