Page Comparison

Locators / Organization Units near me

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

url URL : api/v2/locator

method: GET/POST

authorization: as setup in the Spring.Framework.Security [Link]

Mandatory parameters - you Method:

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

Attribute	Description

description

Example
coordinates		(String) User

location or

's location in the format of Latitude, Longitude

near to which we want to find the organization Units.

comma separate value

points

array of coordinates / decimal
(only available for POST method)

latitude

longitude

Organization Unit

uid

core | OrgUnit UID

UID generated by DHIS2 for a organization unit

code

core | Org Unit Code

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

When

OrgUnit UID / code for

the

ancestor

is

. When provided,

then

all

the locator

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

Boolean

true

Defines if

Specifies whether pagination is required.

page

number

Number

1

Defines which

Determines the page number to

return

be returned.

pageSize

number

Number

10

Defines

Sets the total

PageSize for the response

number of items per page.

distance

number

Number

10

Defines radius

Specifies the radius (in unit specified) within which

you need

to generate the organization

Units

units.

unit

m | km | mi

Options:
m (meters),
km (kilometers), mi (miles)

km

Define

Defines the unit of measurement for

the

distance.

level

number

Number

7

Defines

Indicates the hierarchy level of the organization unit.

Filters

type	Text		Specifies the type of the

orgUnit

location.
phoneNumber

text

Text (

phone

Phone Number)

N/A

DHIS2 core element

| Defines

that defines the phone number

of the location

DHIS2 custom ou attribute

type

text

Defines the type

of the location.

tags

text (csv

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 (csv

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

Text

N/A

Defines the broader area where the

locations

location is

located

situated.

subArea

text

Text

N/A

Defines

Specifies the

subArea where the locations is located

subarea of the location.

text

Text (phone Number)

N/A

Defines

Indicates the

WhatsApp number of the location.

facebook

text | url

Text or URL

N/A

Defines

Provides the

fb url

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

Code Block

language	json

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

Version	Old Version 10	New Version Current
Changes made by	Utsav Ashish Koju	Utsav Ashish Koju
Saved on	Apr 24, 2023	Dec 11, 2023

Versions Compared

Key

Locators / Organization Units near me

Request Parameters

Required Parameters

Please Note

Filters