Catchment Encounters API

Context

A facility may download encounters for patients in their catchment for offline access to patient's records. This applies to any other system like a CHW system, or other subsystems requiring access to data either for clinical or for analytical purpose.

The API returns encounters of patients in a given catchment. The catchment is defined by central systems like a Facility Registry.

In BDHIE context, the catchment is defined as a "location id" defined by the "Location Registry", corresponding to the Geo location codes defined by BBS and provided through Location Registry (DGHS HRM system).

The applicable catchment definition for an establishment is done through the "Facility Registry" (DGHS HRM system).

For example:

Location of Dohar Upazila of Dhaka district is defined as below. The "id" attribute (above) defines the "catchment id" for the catchment encounters API.

Exapmle locations 302618

{
    "code": "18",
    "id": "302618",
    "name": "Dohar",
    "type": "upazila",
    "active": "1",
    "hierarchy": [
        {
            "code": "30",
            "name": "Dhaka",
            "type": "division"
        },
        {
            "code": "26",
            "name": "Dhaka",
            "type": "district"
        },
        {
            "code": "18",
            "name": "Dohar",
            "type": "upazila"
        }
    ]
}

Facility for Dohar Upazila Health Complex can be defined as below.

Exapmle locations 302618

{
    "name": "Dohar Upazila Health Complex",
    "url": "",
    "id": "10000069",
    "active": "1",
    "createdAt": "",
    "updatedAt": "2014-08-03 10:54:51",
    "coordinates": [
        "90.1401381000001",
        "23.5846912"
    ],
    "identifiers": {
        "agency": "DGHS",
        "context": "HRM",
        "id": "65"
    },
    "properties": {
        "ownership": "Fully Government-owned",
        "org_type": "Upazila Health Complex",
        "org_level": "Upazila",
        "care_level": "",
        "services": [],
        "locations": {
            "division_code": "30",
            "district_code": "26",
            "upazila_code": "18",
            "paurasava_code": "",
            "union_code": "",
            "ward_code": ""
        },
        "contacts": {
            "name": "",
            "email": "dohar@uhfpo.dghs.gov.bd",
            "phone": "27768188",
            "mobile": "1711706371",
            "fax": "nil\r"
        },
        "catchment": [
            "302618"
        ]
    }
}

Catchment is defined as extended attribute "catchment" above. Note that a facility may have multiple catchment, in which case, the catchment attribute will be list of comma-separated values of the location id.

For example, if the above facility also serves people of "Dhamrai" upazila of Dhaka district, then the catchment returned be ["302614", "302618"]

NOTE: An establishment can also request encounters for locations included within the catchment as well. For example, "Dohar Upazila Health Complex" can request for "Dhamrai Paurasava" (30261860).

Authentication & Authorization

Only authenticated establishment having requested catchment will be returned with appropriate results. The client_id and From are given when registering with the Identity Provider. The signin API of Identity Provider should be used to get the auth token(To be provided in the X-Auth-Token header). Refer the Identity Provider page for more information on how to use the Identity Provider APIs.

API

URL

GET /catchments/{catchment id}/encounters

Request

{catchment id} - id of catchment requesting patient encounters for.

Headers

X-Auth-Token : {auth token returned from Identity Service Provider}
client_id : {client id of requester in Identity Service Provider}
From : {email_id of requester registered in Identity Service Provider}
Accept - application/atom+xml or application/json

Filters

updatedSince - Return patient encounters updated since a particular date expressed in ISO 8601 format. e.g) 2014-10-16T18:22:20Z
supported formats are listed below. For example, consider date is Nov 03 17:24:52 IST 2014
- yyyy-MM-dd'T'HH:mm:ss.SSSZ - ISO Date with milliseconds. e.g. 2014-11-03T17:24:52.769+0530
- yyyy-mm-dd'T'HH:mm:ssZ - ISO Date with seconds. e.g. 2014-24-03T17:24:52+0530
- yyyy-MM-dd HH:mm:ss.SSSZ - UTC Date with milliseconds e.g. 2014-11-03 17:24:52.769+0530
- yyyy-MM-dd HH:mm:ssZ - UTC Date with seconds e.g. 2014-11-03 17:24:52+0530
- yyyy-MM-dd HH:mm:ss - Current Date with seconds e.g. 2014-11-03 17:24:52
- yyyy-MM-dd - Simple Date e.g 2014-11-03
lastMarker - Return patient encounters are after the given marker. This marker will be ID of one of the entries in the feed. It will give entries which are after the entry which id is givem

Example:- catchments/3026/encounters?updatedSince=2017-03-20T11:21:02.635%2B0530&lastMarker=337b0bb0-0d31-11e7-9fea-667d3bb0eee2

NOTE: If updatedSince and lastMarker both are specified, last marker will be preferred.

NOTE: If no filter is specified, then starting date of the month will be taken as a filter for updatedSince.

Response

The result is a paginated list of encounters published in Atom or Json Feed format, depending on the Accept Header.

You can find more information of the feed and protocol and reference libraries here.

Since the number of encounters can be unfathomably large for a given catchment, the results are almost always paged, with the next-archive (ATOM) or nextUrl (JSON), providing the link to the next set of results, until a time when no more encounters are available, at which point the next-archive/nextUrl will be empty.

The entries contain

id - encounter Id
link - URL to the specific patient encounter
updated - date of receipt of the encounter at SHR.
content - the actual encounter document. For Atom, the content is enclosed in CDATA element. For JSON, the content would be json version of the encounter bundle.

Sample catchment feed for 302618

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
    <title>Patient Encounters</title>
    <link rel="self" type="application/atom+xml" href="http://example.domain/catchments/302618/encounters?updatedSince=2014-11-01T00%3A00%3A00.000%2B0530" />
    <link rel="via" type="application/atom+xml" href="http://example.domain/catchments/302618/encounters?updatedSince=2014-11-01T00%3A00%3A00.000%2B0530" />
    <link rel="next-archive" type="application/atom+xml" href="http://example.domain/catchments/302618/encounters?updatedSince=2014-11-03T16%3A03%3A38.420%2B0530&amp;lastMarker=3d697fbc-78aa-4400-b63f-e0a80d785b1c" />
    <author>
        <name>FreeSHR</name>
    </author>
    <id>d2927fc2-8a11-4bc1-a81a-f8b76e492118</id>
    <generator uri="https://github.com/ICT4H/atomfeed">Atomfeed</generator>
    <updated>2014-11-03T05:26:37Z</updated>
    <entry>
        <title>Encounter:fb7573ce-1a70-41ae-88dd-14a6f26eb2a8</title>
        <link rel="via" type="application/xml" href="/patients/5929349237643935745/encounters/fb7573ce-1a70-41ae-88dd-14a6f26eb2a8" />
        <category term="encounter" />
        <id>fb7573ce-1a70-41ae-88dd-14a6f26eb2a8</id>
        <updated>2014-11-03T05:26:37Z</updated>
        <content type="application/vnd.atomfeed+xml">
            <![CDATA[
                .....
                ..... 
            ]]>
        </content>
    </entry>
    <entry>
        <title>Encounter:df82d092-5583-4ec6-a0f2-22cc36b0d986</title>
        <link rel="via" type="application/xml" href="/patients/5929349992186642433/encounters/df82d092-5583-4ec6-a0f2-22cc36b0d986" />
        <category term="encounter" />
        <id>df82d092-5583-4ec6-a0f2-22cc36b0d986</id>
        <updated>2014-11-03T05:29:37Z</updated>
        <content type="application/vnd.atomfeed+xml">
            <![CDATA[
                .....
                .....
            ]]>
        </content>
    </entry>
    <entry>
        .....
        .....
    </entry>
</feed>

Note:- When pulling encounters for a catchment the API will give all the data which falls under that catchment and catchments below that.