tencent cloud

Tencent Healthcare Data Services

ドキュメントTencent Healthcare Data ServicesAPI DocumentationSearch Operation APIsNumeric Search API

Numeric Search API

Download
フォーカスモード
フォントサイズ
最終更新日: 2026-08-28 16:06:55
AI翻訳

API Description

This function is used to perform conditional searches on resources based on numeric fields. It is commonly applied in scenarios such as test results, vital signs, and measurement values. Clients can access the target resource type endpoint via the HTTP GET method and filter conditions such as test item codes, numerical values, and units using standard search parameters.
This example demonstrates several common methods for searching laboratory test results based on the Observation resource, including:
Retrieve all laboratory test results for the specified patient.
Retrieve a specific test result for all patients.
Retrieve test results that fall within a specific numerical range.

Input parameters

Parameter Name
Type
Required
Description
HTTP Method
String
Yes
Fixed as GET.
URL
String
Yes
The search address, in the format [baseUrl]/[resourceType]?[searchParams].
Authorization
String
Yes
The access token, in the format Bearer <AccessToken>. For details on how to obtain it, see Calling Method.
Accept
String
No
The response format. It is recommended to use application/fhir+json.
subject
String
No
Filters by the associated patient, typically in the format Patient/{id}. Here, {id} is the unique identifier of the referenced resource, which can be obtained via the Basic Search API or the console resource viewer.
category
String
No
Filters by resource category. In this example, it is the laboratory category, such as http://hl7.org/fhir/observation-category%7Claboratory.
code
String
No
Filters by test item code, typically a standard terminology code, such as http://loinc.org%7C6298-4. Note that the vertical bar | in the URL system%7Ccode must be encoded as %7C.
value-quantity
String
No
Filters by value and unit, typically in the format [prefix][value]%7C[system]%7C[unit]. Here, prefix is the comparison prefix (for example, lt, le, gt, ge), and the vertical bar | must be encoded as %7C.
Note:
The category parameter can be used to restrict the results to only laboratory-type Observation resources.
The code parameter is commonly used to search for a specific test item, such as a potassium ion test.
The value-quantity parameter supports comparison prefixes, such as lt, le, gt, ge, and others.
For unit filtering, it is generally recommended to include both the unit system and the unit code to improve matching accuracy.
In FHIR search parameters, the vertical bar \\| used to separate system and code must be encoded as %7C in the URL; otherwise, the request may fail.

Output Parameters

Upon a successful API call, the HTTP status code 200 OK is typically returned. The response body is usually a Bundle resource, which contains a list of Observation resources that meet the specified criteria, along with pagination information.
Key Response Body Field Descriptions:
Field
Type
Description
resourceType
String
Returns the resource type, usually Bundle.
id
String
Unique ID of the Bundle resource, usually a UUID.
meta
Object
Metadata of the Bundle, containing fields such as lastUpdated.
meta.lastUpdated
String
Generation time of the Bundle, in ISO 8601 format.
type
String
The Bundle type is usually searchset in search scenarios.
link
Array
Pagination link information, containing relation and url.
link[].relation
String
Type of the link relation, such as self, next, and previous.
link[].url
String
The complete request URL for the corresponding pagination.
entry
Array
The list of search results.
entry[].fullUrl
String
The complete access URL of the resource.
entry[].resource
Object
The content of the matched Observation resource.
entry[].resource.id
String
Unique ID of the resource.
entry[].resource.meta
Object
Metadata of the resource, containing fields such as versionId, lastUpdated, and source.
entry[].resource.status
String
The status of the observation result, such as final, preliminary, and so on.
entry[].resource.category
Array
Resource categorization information, such as laboratory classification.
entry[].resource.code
Object
Information about the test item code.
entry[].resource.subject
Object
Reference information of the associated patient.
entry[].resource.valueQuantity
Object
Information about the test value and its unit.
entry[].search.mode
String
The search hit mode, such as match.

Examples

Request Example

Example 1: Retrieve all laboratory test results for the specified patient.
GET /INSTANCE_ID/fhir/Observation?subject=Patient/h0e270d9-ed56-4041-9dec-a45a73461c66&category=http://hl7.org/fhir/observation-category%7Claboratory HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json
Example 2: Retrieve a specific test result for all patients.
GET /INSTANCE_ID/fhir/Observation?code=http://loinc.org%7C6298-4 HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json
Example 3: Retrieve potassium ion results with a value less than 4.0 mmol/L.
GET /INSTANCE_ID/fhir/Observation?code=http://loinc.org%7C6298-4&value-quantity=lt4.0%7Chttp://unitsofmeasure.org%7Cmmol/L HTTP/1.1
Host: HOSTNAME
Authorization: Bearer <AccessToken>
Accept: application/fhir+json

Response Example

{
  "resourceType": "Bundle",
  "id": "a9fdb12d-8a08-4cfb-8d8c-13f8a0fa50ad",
  "meta": {
    "lastUpdated": "2026-07-08T21:24:14.191+08:00"
  },
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://HOSTNAME/INSTANCE_ID/fhir/Observation?code=http%3A%2F%2Floinc.org%7C6298-4&value-quantity=lt4.0%7Chttp%3A%2F%2Funitsofmeasure.org%7Cmmol%2FL"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://HOSTNAME/INSTANCE_ID/fhir/Observation/9a6adc7c-2496-43b9-881f-72a3f3067544",
      "resource": {
        "resourceType": "Observation",
        "id": "9a6adc7c-2496-43b9-881f-72a3f3067544",
        "meta": {
          "versionId": "1",
          "lastUpdated": "2026-07-08T21:24:13.487+08:00",
          "source": "#nB7pryS0ElzarOdc"
        },
        "status": "final",
        "category": [
          {
            "coding": [
              {
                "system": "http://hl7.org/fhir/observation-category",
                "code": "laboratory"
              }
            ]
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "6298-4",
              "display": "Potassium"
            }
          ]
        },
        "subject": {
          "reference": "Patient/f25a8f0c-3473-4deb-8917-45d967263a1e"
        },
        "valueQuantity": {
          "value": 3.8,
          "system": "http://unitsofmeasure.org",
          "code": "mmol/L"
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

Error Codes

Common error codes are listed below. For more error codes, see Error Codes.
Error Code
Description
400 Bad Request
The search parameter format is incorrect, or the numeric/unit expression is invalid.
401 Unauthorized
Not authenticated, and valid credentials are missing.
403 Forbidden
Authenticated but not authorized to search the resource.
404 Not Found
The specified resource type does not exist.
422 Unprocessable Entity
The search parameter syntax is correct, but it fails business or rule validation.
500 Internal Server Error
Internal server processing exception.

前の記事へ: Search API Reference次の記事へ: Date and Time Search API

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック