PHDI Ingestion Service (1.2.11)

Download OpenAPI specification:Download

CDC Public Health Data Infrastructure: dmibuildingblocks@cdc.gov URL: https://cdcgov.github.io/phdi-site/ License: Creative Commons Zero v1.0 Universal

Getting Started with the PHDI Ingestion Service

Introduction

The PHDI ingestion service offers a REST API with endpoints for standardization and harmonization of FHIR messages. It offers name standardization, date of birth standardization, phone number standardization, geocoding, and several utilities for working with FHIR servers.

Running the Ingestion Service

The ingestion service can be run using Docker (or any other OCI container runtime e.g., Podman), or directly from the Python source code.

Running with Docker (Recommended for production)

To run the ingestion service with Docker follow these steps.

Confirm that you have Docker installed by running docker -v. If you do not see a response similar to what is shown below, follow these instructions to install Docker.
```
❯ docker -v
Docker version 20.10.21, build baeda1f
```
Download a copy of the Docker image from the PHDI repository by running docker pull ghcr.io/cdcgov/phdi/ingestion:latest.
Run the service with docker run -p 8080:8080 ghcr.io/cdcgov/phdi/ingestion:latest.

Congratulations, the ingestion service should now be running on localhost:8080!

Running from Python Source Code

We recommend running the ingestion service from a container, but if that is not feasible for a given use case, it may also be run directly from Python using the steps below.

Ensure that both Git and Python 3.10 or higher are installed.
Clone the PHDI repository with git clone https://github.com/CDCgov/phdi.
Navigate to /phdi/containers/ingestion/.
Make a fresh virtual environment with python -m venv .venv.
Activate the virtual environment with source .venv/bin/activate (MacOS and Linux), venv\Scripts\activate (Windows Command Prompt), or .venv\Scripts\Activate.ps1 (Windows PowerShell).
Install all of the Python dependencies for the ingestion service with pip install -r requirements.txt into your virtual environment.
Run the FHIR Converter on localhost:8080 with python -m uvicorn app.main:app --host 0.0.0.0 --port 8080.

Building the Docker Image

To build the Docker image for the ingestion service from source code instead of downloading it from the PHDI repository, follow these steps.

Ensure that both Git and Docker are installed.
Clone the PHDI repository with git clone https://github.com/CDCgov/phdi.
Navigate to /phdi/containers/ingestion/.
Run docker build -t ingestion ..

The API

When viewing these docs from the /redoc endpoint on a running instance of the ingestion service or the PHDI website, detailed documentation on the API will be available below.

Health Check

Check service status. If an HTTP 200 status code is returned along with '{"status": "OK"}' then the service is available and running properly.

Responses

Response samples

200

Content type

application/json

{"status": "OK"
}

fhir/harmonization

Standardize Names Endpoint

Standardize the names in the provided FHIR bundle or resource.

:param input: A dictionary with the schema specified by the StandardizeNamesInput model.

:return: A FHIR bundle or resource with standardized names.

Request Body schema: application/json

data required	object (Data) A FHIR resource or bundle in JSON format.
trim	boolean (Trim) Default: true When true, leading and trailing spaces are removed.
overwrite	boolean (Overwrite) Default: true If true, `data` is modified in-place; if false, a copy of `data` is modified and returned.
case	string (Case) Default: "upper" Enum: "upper" "lower" "title"
remove_numbers	boolean (Remove Numbers) Default: true If true, delete numeric characters; if false leave numbers in place.

Responses

Request samples

Payload

Content type

application/json

{"data": {"resourceType": "Patient",
"id": "c53f9ad8-34c1-ce05-c0f6-7a0ea7bd8483",
"name": [{"family": "Doe  ",
"given": ["Jan3e"
],
"use": "official"
}
]
},
"trim": true,
"overwrite": true,
"case": "upper",
"remove_numbers": true
}

Response samples

200
422

Content type

application/json

{"status_code": "200",
"bundle": {"resourceType": "Patient",
"id": "c53f9ad8-34c1-ce05-c0f6-7a0ea7bd8483",
"name": [{"family": "DOE",
"given": ["JANE"
],
"use": "official"
}
]
}
}

Standardize Phones Endpoint

Standardize the phone numbers in the provided FHIR bundle or resource.

Requires an address so that country code can be generated.

:param input: A dictionary with the schema specified by the StandardizePhonesInput model.

:return: A FHIR bundle with standardized phone numbers.

Request Body schema: application/json

data required	object (Data) A FHIR resource or bundle in JSON format.
overwrite	boolean (Overwrite) Default: true If true, `data` is modified in-place; if false, a copy of `data` is modified and returned.

Responses

Request samples

Payload

Content type

application/json

{"data": {"resourceType": "Patient",
"id": "c53f9ad8-34c1-ce05-c0f6-7a0ea7bd8483",
"address": [{"line": "1600 Pennsylvania Ave",
"city": "Washington",
"state": "DC",
"postalCode": "12345",
"use": "home"
}
],
"telecom": [{"system": "phone",
"value": "(555) 867-5309",
"use": "home"
}
]
},
"overwrite": true
}

Response samples

200
422

Content type

application/json

{"status_code": "200",
"bundle": {"resourceType": "Patient",
"id": "c53f9ad8-34c1-ce05-c0f6-7a0ea7bd8483",
"address": [{"line": "1600 Pennsylvania Ave",
"city": "Washington",
"state": "DC",
"postalCode": "12345",
"use": "home"
}
],
"telecom": [{"system": "phone",
"value": "+15558675309",
"use": "home"
}
]
}
}

Standardize Dob Endpoint

Standardize the patient date of birth in the provided FHIR bundle or resource.

Dates are changed to the FHIR standard of YYYY-MM-DD.

Returns a FHIR bundle with standardized birth dates.

Request Body schema: application/json

data required	object (Data) A FHIR resource or bundle in JSON format.
overwrite	boolean (Overwrite) Default: true If true, `data` is modified in-place; if false, a copy of `data` is modified and returned.
format	string (Format) Default: "Y%-m%-d%"

Responses

Request samples

Payload

Content type

application/json

{"data": {"resourceType": "Patient",
"id": "c53f9ad8-34c1-ce05-c0f6-7a0ea7bd8483",
"name": [{"family": "Doe",
"given": ["Jane"
],
"use": "official"
}
],
"birthDate": "05/30/1955"
},
"overwrite": true,
"format": "%m/%d/%Y"
}

Response samples

200
422

Content type

application/json

{"status_code": "200",
"bundle": {"resourceType": "Patient",
"id": "c53f9ad8-34c1-ce05-c0f6-7a0ea7bd8483",
"name": [{"family": "Doe",
"given": ["Jane"
],
"use": "official"
}
],
"birthDate": "1955-05-30"
}
}

fhir/geospatial

Geocode Bundle Endpoint

Given a FHIR bundle and a specified geocode method, geocode all patient addresses across all patient resources in the bundle.

Two geocode methods are currently supported - Smarty and the U.S. Census.

If using the Smarty provider, an smarty_auth_id, smarty_auth_token and license_type must be provided. If they are not provided as request parameters, then the service will attempt to obtain them through environment variables. If they cannot be found in either the request parameters or environment variables, an HTTP 400 status will be returned.

Request Body schema: application/json

bundle required	object (Bundle) A FHIR resource or bundle in JSON format.
geocode_method required	string (Geocode Method) Enum: "smarty" "census" The geocoding service to be used.
smarty_auth_id	string (Smarty Auth Id) Default: "" Authentication ID for the geocoding service. Must be provided in the request body or set as an environment variable of the service if `geocode_method` is `smarty`.
smarty_auth_token	string (Smarty Auth Token) Default: "" Authentication Token for the geocoding service. Must be provided in the request body or set as an environment variable of the service if `geocode_method` is `smarty`.
license_type	string (License Type) Default: "us-rooftop-geocoding-enterprise-cloud" Enum: "us-standard-cloud" "us-core-cloud" "us-rooftop-geocoding-cloud" "us-rooftop-geocoding-enterprise-cloud" "us-autocomplete-pro-cloud" "international-global-plus-cloud" License type for the geocoding service. Must be provided in the request body or set as an environment variable of the service if `geocode_method` is `smarty`.
overwrite	boolean (Overwrite) Default: true If true, `data` is modified in-place; if false, a copy of `data` modified and returned.

Responses

Request samples

Payload

Content type

application/json

{"bundle": { },
"geocode_method": "smarty",
"smarty_auth_id": "",
"smarty_auth_token": "",
"license_type": "us-standard-cloud",
"overwrite": true
}

Response samples

200
422

Content type

application/json

Example

Smarty Geocode Response

{"status_code": "200",
"bundle": {"resourceType": "Bundle",
"entry": [{"resource": {"resourceType": "Patient",
"name": [{"family": "DOE",
"given": ["JANE"
]
}
],
"address": [{"line": ["1600 Pennsylvania Ave NW"
],
"city": "Washington",
"state": "DC",
"postalCode": "20500",
"country": "USA",
"extension": [{"url": "http://hl7.org/fhir/StructureDefinition/geolocation",
"extension": [{"url": "latitude",
"valueDecimal": 38.897606
},
{"url": "longitude",
"valueDecimal": -77.036674
}
]
}
]
}
]
}
}
]
}
}

fhir/linkage

Add Patient Identifier In Bundle Endpoint

Add a salted hash identifier to every patient resource in a FHIR bundle using. If a salt is not provided in the request the value of the 'SALT_STR' environment variable will be used. In the case where a salt is not provided and 'SALT_STR' is not defined an HTTP 500 status code is returned.

:param input: A JSON formated request body with schema specified by the AddPatientIdentifierInBundleInput model. :return: A FHIR bundle where every patient resource contains a hashed identifier.

Request Body schema: application/json

bundle required	object (Bundle) A FHIR bundle
salt_str	string (Salt Str) Default: "" The salt to use with the hash. This is intended to prevent reverse engineering of the PII used to create the hash.
overwrite	boolean (Overwrite) Default: true If true, `data` is modified in-place; if false, a copy of `data` modified and returned.

Responses

Request samples

Payload

Content type

application/json

{"bundle": { },
"salt_str": "",
"overwrite": true
}

Response samples

200
422

Content type

application/json

{"status_code": "string",
"message": "string",
"bundle": { }
}

fhir/transport

Upload Bundle To Fhir Server Endpoint

Upload all of the resources in a FHIR bundle to a FHIR server.

:param input: A JSON formated request body with schema specified by the UploadBundleToFhirServerInput model. :return: A dictionary containing the status code and body of the response received from the FHIR server.

Request Body schema: application/json

bundle required	object (Bundle) A FHIR bundle (type 'batch' or 'transaction') to post. Each entry in the bundle must contain a `request` element in addition to a `resource`. The FHIR API provides additional details on creating FHIR-conformant batch/transaction bundles.
cred_manager	string (Cred Manager) Enum: "azure" "gcp" The credential manager used to authenticate to the FHIR server.
fhir_url	string (Fhir Url) The url of the FHIR server to upload to.

Responses

Request samples

Payload

Content type

application/json

{"bundle": { },
"cred_manager": "azure",
"fhir_url": "string"
}

Response samples

200
422

Content type

application/json

{"status_code": "string",
"message": "string",
"bundle": { }
}

cloud/storage

Write Blob To Cloud Storage Endpoint

Upload the information from a blob into a specified cloud providers storage organizing it by a bucket name as well as a file name.

:param input: A JSON formated request body (blob) with schema specified by the WriteBlobToStorageInput model. :return: A dictionary containing the status code and body of the response received from the cloud provider.

Request Body schema: application/json

blob required	object (Blob) Contents of a blob to be written to cloud storage.
cloud_provider	string (Cloud Provider) Enum: "azure" "gcp" The cloud provider hosting the storage resource that the blob will be uploaded to. Must be provided in the request body or set as an environment variable of the service.
bucket_name	string (Bucket Name) Name of the cloud storage bucket that the blob should be uploaded to. Must be provided in the request body or set as an environment variable of the service.
file_name required	string (File Name) Name of the blob
storage_account_url	string (Storage Account Url) Default: "" The URL of an Azure storage account. Must be provided in the request body or set as an environment variable of the service is 'cloud_provider' is 'azure'.

Responses

Request samples

Payload

Content type

application/json

{"blob": { },
"cloud_provider": "azure",
"bucket_name": "string",
"file_name": "string",
"storage_account_url": ""
}

Response samples

201
422

Content type

application/json

{"status_code": "string",
"message": "string",
"bundle": { }
}