Catchment Encounters API

Context

A facility may download encounters for patients in their catchment for offline access to patients' 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

/locations/302618.json

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

The "id" attribute (above) defines the "catchment id" for the catchment encounters API.

Facility may be defined as

/facilities/10000069.json

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

API

URL

GET /catchments/{catchment id}/encounters

Request

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

Headers

Accept - application/atom+xml or application/json
facilityId - identifier for the facility. NOTE: this is temporary.

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

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

Response

Status: 200 OK

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.

example:

/catchments/302618/encounters

<?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>