Utils

Last updated: 27 Jun 2025

Making requests with Http #

The Canvas SDK offers a helper class for completing HTTP calls.

from canvas_sdk.utils import Http
http = Http()

get #

Sends a GET request.

Parameters:

Name	Type	Required	Description
`url`	string	`true`	The url of the request.
`headers`	dict	`false`	The headers to include in the request.

Example:

http = Http()
http.get("https://my-url.com/", headers={"Authorization": f"Bearer token"})

post #

Sends a POST request.

Parameters:

Name	Type	Required	Description
`url`	string	`true`	The url of the request.
`headers`	dict	`false`	The headers to include in the request.
`json`	dict	`false`	The json to include in the request.
`data`	dict or string	`false`	The data to include in the request.

Example:

http = Http()
http.post(
    "https://my-url.com/",
    headers={"Authorization": f"Bearer token"},
    json={"post": "json"},
    data="this-is-my-data"
)

put #

Sends a PUT request.

Parameters:

Name	Type	Required	Description
`url`	string	`true`	The url of the request.
`headers`	dict	`false`	The headers to include in the request.
`json`	dict	`false`	The json to include in the request.
`data`	dict or string	`false`	The data to include in the request.

Example:

http = Http()
http.put(
    "https://my-url.com/",
    headers={"Authorization": f"Bearer token"},
    json={"put": "json"},
    data="this-is-my-data"
)

patch #

Sends a PATCH request.

Parameters:

Name	Type	Required	Description
`url`	string	`true`	The url of the request.
`headers`	dict	`false`	The headers to include in the request.
`json`	dict	`false`	The json to include in the request.
`data`	dict or string	`false`	The data to include in the request.

Example:

http = Http()
http.patch(
    "https://my-url.com/",
    headers={"Authorization": f"Bearer token"},
    json={"patch": "json"},
    data="this-is-my-data"
)

Making concurrent requests with Http #

There is an interface for executing HTTP requests in parallel.

The batch_requests method will execute the requests in parallel using multithreading, and return once all the requests have completed.

The first parameter to the method is an iterable of BatchableRequest objects. These can be created with the following helper functions:

batch_get
batch_post
batch_put
batch_patch

The parameters that these helper functions accept match what the corresponding single-request methods accept.

The timeout parameter allows for specifying a timeout value in seconds; if a request has not completed before the timeout value, an error will be returned for that request. The maximum allowed value for timeout is 30 seconds. If timeout is not specified, it will be set to the maximum value.

The return value will be a list of responses to the requests. The order of the return value will correspond to the order of the provided requests.

Parameters:

Name	Type	Required	Description
`batch_requests`	Iterable[BatchableRequest]	`true`	The list of batched requests.
`timeout`	integer	`false`	The timeout value in seconds.

Example:

from canvas_sdk.utils import Http, batch_get, batch_post, batch_put, batch_patch

http = Http()

requests = [
    batch_get("https://my-url.com/", headers={"Authorization": f"Bearer token"}),
    batch_post("https://my-url.com/", headers={"Authorization": f"Bearer token"}, json={"post": "json"}),
    batch_put("https://my-url.com/", headers={"Authorization": f"Bearer token"}, data="this-is-my-data"),
    batch_patch("https://my-url.com/", headers={"Authorization": f"Bearer token"}, json={"patch": "json"})
]

responses = http.batch_requests(requests, timeout=10)

Making requests to the Ontologies service #

Plugin authors can make requests to our Ontologies service using the ontologies_http wrapper.

In addition to the json() method of the response, which you’ll use to access the response itself, you can also access the status_code to verify that the request was succcessful.

Searching for medications #

Plugin authors can search for medications by NDC code, RxNorm RXCUI, or full-text search.

from urllib.parse import urlencode
from canvas_sdk.utils.http import ontologies_http

# full text search of the medication name, description, and synonyms
response_json = ontologies_http.get_json(f"/fdb/grouped-medication/?{urlencode({"search": "tylenol"})}").json()

# response_json contains a "results" key with this object as the first result:
# {
#   "results": [
#     {
#       "description_and_quantity": "Athenol 325 mg tablet",
#       "med_medication_id": 436095,
#       "search_rank": 0.082745634,
#       "search_terms": "Athenol 325 mg tablet|ACETAMINOPHEN ORAL|ACETAMINOPHEN PO|ACETAMINOPHEN VIA FEEDING TUBE|TYLENOL|TYLENOL ORAL|TYLENOL PO|APAP|APAP ORAL|APAP PO|PANADOL|PANADOL ORAL|PANADOL PO|ATHENOL 325 MG TABLET|ACETAMINOPHEN 325 MG TABLET",
#       "med_medication_description": "Athenol 325 mg tablet",
#       "clinical_quantities": [
#         {
#           "erx_quantity": "1.0000000",
#           "representative_ndc": "11822317640",
#           "clinical_quantity_description": "tablet",
#           "erx_ncpdp_script_quantity_qualifier_code": "C48542",
#           "erx_ncpdp_script_quantity_qualifier_description": "Tablet"
#         }
#       ],
#       "etc_path_id": [
#         3645,
#         574,
#         578,
#         577
#       ],
#       "etc_path_name": [
#         "Analgesic, Anti-inflammatory or Antipyretic",
#         "Analgesic, Anti-inflammatory or Antipyretic - Non-Opioid",
#         "Analgesic or Antipyretic Non-Opioid and Combinations",
#         "Analgesic or Antipyretic Non-Opioid"
#       ],
#       "rxnorm_rxcui": "313782"
#     },
#     ...
#   ]
# }

# search for a specific RxNorm RXCUI
response_json = ontologies_http.get_json(f"/fdb/grouped-medication/?{urlencode({"rxnorm_rxcui": 313782})}").json()

# response_json contains the same general format as above

# look up by NDC
response_json = ontologies_http.get_json(f"/fdb/ndc-to-medication/76420037215/").json()

# response_json contains this object:
# {
#   "description_and_quantity": "Aphen 325 mg tablet",
#   "med_medication_id": 572345,
#   "search_terms": "Aphen 325 mg tablet|APHEN 325 MG TABLET|ACETAMINOPHEN 325 MG TABLET",
#   "med_medication_description": "Aphen 325 mg tablet",
#   "clinical_quantities": [
#     {
#       "erx_quantity": "1.0000000",
#       "representative_ndc": "76420037215",
#       "clinical_quantity_description": "tablet",
#       "erx_ncpdp_script_quantity_qualifier_code": "C48542",
#       "erx_ncpdp_script_quantity_qualifier_description": "Tablet"
#     }
#   ],
#   "etc_path_id": [
#     3645,
#     574,
#     578,
#     577
#   ],
#   "etc_path_name": [
#     "Analgesic, Anti-inflammatory or Antipyretic",
#     "Analgesic, Anti-inflammatory or Antipyretic - Non-Opioid",
#     "Analgesic or Antipyretic Non-Opioid and Combinations",
#     "Analgesic or Antipyretic Non-Opioid"
#   ],
#   "rxnorm_rxcui": "313782"
# }

# look up multiple NDCs
response_json = ontologies_http.get_json(f"/fdb/ndcs-to-medications/76420037215,11822317640/").json()

# response_json is a dictionary where each key is an NDC and each each attribute contains the
# object formatted as the individual ndc-to-medication search above

# look up by RxNorm RXCUI

# response_json is a list containing objects of this type:
# [
#   {
#     "med_medication_id": 156060,
#     "clinical_formulation_id": {
#       "clinical_formulation_id": 4489.0,
#       "hierarchical_specific_therapeutic_class_code": "H3E",
#       "dosage_form_code_2_character": "TA",
#       "route_of_administration_code_1_character": "1",
#       "drug_strength_description": "325 MG",
#       "therapeutic_class_code_generic": 2.0,
#       "therapeutic_class_code_standard": 41.0,
#       "drug_category_code": "0",
#       "gcn_seqno_level_multi_source_single_source_indicator": "1",
#       "gender_specific_drug_indicator": "0",
#       "hierarchical_specific_therapeutic_class_code_sequence_number": 271.0,
#       "drug_strength_description_60": "325 mg",
#       "ingredient_list_description": 1866.0,
#       "interactions": [
#         1674.0,
#         27763.0,
#         29424.0,
#         30280.0,
#         30534.0
#       ]
#     },
#     "clinical_quantities": [
#
#     ],
#     "med_routed_dosage_form_medication_id": 12758.0,
#     "med_strength": "325",
#     "med_strength_unit_of_measure": "mg",
#     "med_medication_description": "Dolono 325 mg tablet",
#     "med_gcn_seqno_assignment_code": "1",
#     "med_medication_name_source_code": "1",
#     "med_reference_federal_legend_indicator": "2",
#     "med_reference_federal_dea_class_code": "0",
#     "med_reference_multi_source_code": "1",
#     "med_reference_generic_medication_name_code": "2",
#     "med_reference_generic_comparative_price_code": "9",
#     "med_reference_generic_price_spread_code": "9",
#     "med_reference_innovator_indicator": "0",
#     "med_reference_generic_therapeutic_equivalence_code": "4",
#     "med_reference_desi_indicator": "9",
#     "med_reference_desi2_indicator": "9",
#     "med_medication_status_code": "3",
#     "med_generic_medication_identifier": 160401.0
#   },
#   ...
# ]

Making requests to the Pharmacy service #

Plugin authors can make requests to our Pharmacy service using the PharmacyHttp client. This client provides a simplified interface for searching pharmacies and retrieving pharmacy details.

from canvas_sdk.utils.http import pharmacy_http

Unlike the general Http client, PharmacyHttp only provides two specific methods for pharmacy operations. Direct HTTP methods (get, post, put, patch) are not available.

Searching for pharmacies #

Search for pharmacies by name, with optional location-based filtering.

Parameters:

Name	Type	Required	Description
`search_term`	string	`true`	The search query for pharmacy name or organization.
`latitude`	string	`false`	Latitude coordinate for location-based search.
`longitude`	string	`false`	Longitude coordinate for location-based search.

Example:

from canvas_sdk.utils.http import pharmacy_http

# Basic search by name
results = pharmacy_http.search_pharmacies("CVS")

# Search with location filtering
results = pharmacy_http.search_pharmacies(
    "pharmacy",
    latitude="40.7128",
    longitude="-74.0060"
)

# The results list contains pharmacy objects like:
# [
#   {
#     "id": 123456,
#     "distance_miles": 0.8,
#     "ncpdp_id": "1234567",
#     "store_number": "#1234",
#     "organization_name": "CVS Pharmacy #1234",
#     "address_line_1": "123 MAIN ST",
#     "address_line_2": "",
#     "city": "New York",
#     "state": "NY",
#     "zip_code": "10001",
#     "phone_primary": "2125551234",
#     "fax": "2125555678",
#     "latitude": 40.7128,
#     "longitude": -74.0060,
#     "npi": "1234567890",
#     "specialty_type": "Retail",
#     ...
#   },
#   ...
# ]

Looking up a pharmacy by NCPDP ID #

Retrieve detailed information about a specific pharmacy using its NCPDP (National Council for Prescription Drug Programs) identifier.

Parameters:

Name	Type	Required	Description
`ncpdp_id`	string	`true`	The NCPDP identifier of the pharmacy.

Example:

from canvas_sdk.utils.http import pharmacy_http

# Look up a specific pharmacy
pharmacy = pharmacy_http.get_pharmacy_by_ncpdp_id("1234567")

# The response contains detailed pharmacy information:
# {
#   "id": 123456,
#   "ncpdp_id": "1234567",
#   "store_number": "#1234",
#   "organization_name": "Example Pharmacy #1234",
#   "address_line_1": "123 MAIN ST",
#   "address_line_2": "",
#   "city": "New York",
#   "state": "NY",
#   "zip_code": "10001",
#   "country": "US",
#   "standardized_address_line_1": "123 Main St",
#   "standardized_city": "New York",
#   "standardized_state": "NY",
#   "standardized_zip_code": "100010000",
#   "phone_primary": "2125551234",
#   "fax": "2125555678",
#   "email": "",
#   "active_start_time": "2020-01-01T00:00:00Z",
#   "active_end_time": "2099-12-31T23:59:59Z",
#   "service_level": "New~Refill~Change~Cancel~ControlledSubstance",
#   "npi": "1234567890",
#   "specialty_type": "Retail",
#   "dea_number": "",
#   "organization_type": "Pharmacy",
#   "organization_id": 1234567,
#   "latitude": 40.7128,
#   "longitude": -74.0060,
#   ...
# }

Response fields #

Both methods return pharmacy objects with the following key fields:

ncpdp_id: Unique NCPDP identifier for the pharmacy
organization_name: Name of the pharmacy
address_line_1, address_line_2, city, state, zip_code: Physical address
phone_primary: Primary phone number
fax: Fax number
npi: National Provider Identifier
specialty_type: Type of pharmacy (e.g., “Retail”, “Mail Order”)
service_level: Services available (e.g., “New~Refill~Change~Cancel~ControlledSubstance”)
latitude, longitude: Geographic coordinates
distance_miles: Distance from search location (only present in search results when location is provided)

Making requests with Http #

get #

post #

put #

patch #

Making concurrent requests with Http #

Making requests to the Ontologies service #

Searching for medications #

Making requests to the Pharmacy service #

Searching for pharmacies #

Looking up a pharmacy by NCPDP ID #

Response fields #

On this page