API Reference

This section provides detailed information about the API endpoints for the Health Recommendation System.

Health Recommendations

POST /recommend

Generate a health service recommendation based on the input query.

Request Body

{
   "query": "I need mental health support",
   "latitude": 43.6532,
   "longitude": -79.3832,
   "radius": 5000,
   "rerank": false
}
Request JSON Object:

  • query (string) – The user’s health-related query (required)

  • latitude (number) – Optional latitude for location-based search

  • longitude (number) – Optional longitude for location-based search

  • radius (number) – Optional search radius in meters (default: 5000)

  • rerank (boolean) – Optional flag to enable/disable reranking of the services (default: false)

Response JSON Object:

  • recommendation (string) – Generated recommendation text

  • services (array) – List of relevant health services

Response Body

{
   "message": "Based on your query...",
   "is_emergency": false,
   "is_out_of_scope": false,
   "services": [
      {
         "id": "service_id",
         "name": "Service Name",
         "description": "Service description",
         "categories": ["category1", "category2"],
         "address": "123 Health St",
         "phone_numbers": [{
            "number": "+1-123-456-7890",
            "type": "Main"
         }],
         "website": "https://example.com",
         "hours": "Monday-Friday 9AM-5PM"
      }
   ],
   "no_services_found": false
}
Response JSON Object:

  • message (string) – Generated recommendation text

  • is_emergency (boolean) – Indicates if the query suggests an emergency

  • is_out_of_scope (boolean) – Indicates if the query is outside service scope

  • services (array) – List of relevant health services (optional)

  • no_services_found (boolean) – Indicates if no matching services were found

Status Codes:

Question Generation

GET /questions

Generate follow-up questions based on the initial query and recommendation.

Example Request

GET /questions?query=mental+health+support&recommendation=Based+on+your+query...
Query Parameters:

  • query (string) – The user’s original health query (required)

  • recommendation (string) – The previously generated recommendation (required)

Response Body

{
   "questions": [
      "Do you prefer in-person or virtual care?",
      "What type of mental health support are you looking for?"
   ]
}
Response JSON Object:

  • questions (array) – List of generated follow-up questions

Status Codes:

Recommendation Refinement

POST /refine_recommendations

Refine the initial recommendation based on answers to follow-up questions.

Request Body

{
   "query": {
      "query": "mental health support",
      "latitude": 43.6532,
      "longitude": -79.3832,
      "radius": 5000
   },
   "questions": ["Do you prefer in-person or virtual care?"],
   "answers": ["in-person"],
   "recommendation": "Previous recommendation text..."
}
Request JSON Object:

  • query (object) – Query object containing:

  • query.query (string) – The user’s health-related query (required)

  • query.latitude (number) – Optional latitude for location-based search

  • query.longitude (number) – Optional longitude for location-based search

  • query.radius (number) – Optional search radius in meters

  • questions (array) – List of follow-up questions (required)

  • answers (array) – User’s answers to the follow-up questions (required)

  • recommendation (string) – The previous recommendation (required)

Response Body

{
   "message": "Based on your preferences...",
   "is_emergency": false,
   "is_out_of_scope": false,
   "services": [
      {
         "id": "service_id",
         "name": "Service Name",
         "description": "Service description"
      }
   ],
   "no_services_found": false
}
Response JSON Object:

  • message (string) – Refined recommendation text

  • is_emergency (boolean) – Updated emergency status

  • is_out_of_scope (boolean) – Updated scope status

  • services (array) – Updated list of relevant services (optional)

  • no_services_found (boolean) – Indicates if no matching services were found

Status Codes:

Service Information

GET /services/all

Retrieve all available health services from the database.

Response Body

[
   {
      "id": "service_id",
      "name": "Service Name",
      "description": "Service description",
      "categories": ["category1", "category2"],
      "address": "123 Health St",
      "phone_numbers": [{
         "number": "+1-123-456-7890",
         "type": "Main"
      }],
      "website": "https://example.com",
      "hours": "Monday-Friday 9AM-5PM"
   }
]
Response JSON Object:

  • services (array) – List of all health services

Status Codes:
GET /services/count

Get the total number of available health services.

Response Body

{
   "count": 150
}
Response JSON Object:

  • count (integer) – Total number of services in the database

Status Codes:

Error Responses

All endpoints may return the following error responses:

{
   "detail": "Error message describing what went wrong"
}

Common HTTP Status Codes

  • 200 OK: Request successful

  • 400 Bad Request: Invalid parameters

  • 422 Unprocessable Entity: Invalid request body

  • 500 Internal Server Error: Server-side error

API Benchmark

The following table shows latency benchmarks for the /recommend API endpoint. Tests were run with different combinations of query parameters and reranking options. Each request was made sequentially to measure individual request latency accurately. The summary statistics are generating from 50 runs with a timeout of 30 seconds w/ no delay between each request.

Test Case

Mean (s)

Median (s)

Std Dev (s)

Min (s)

Max (s)

Sample Size

Query only

6.686

5.985

2.336

4.504

19.362

48

Query w/ reranking

8.729

8.547

1.964

5.249

14.133

50

Query w/ location

6.795

6.260

3.560

3.277

27.860

46

Query w/ location and reranking

8.197

7.934

1.867

5.720

13.688

50