Description
The following use case will retrieve a list of service locations based on a location area.
In the example we use a zip code to filter services.
Quote of Use Case
“I would like to get a list of all services that serve zip code 49456”
Step 1 - Get an access token
This will retrieve an access token from CIE Identity Provider. Please note that if the system has already retrieved a access token that has not yet expired then that existing unexpired token can be used with other calls. An access token is valid for 24 hours after it has been minted. The following explains on how to get Authorization
Step 2 - Call [GET /services/areas] Get a list of valid service area terms
The social services directory tags each service by an area which can be used to filter the results of the Call. The following will get a list of searchable areas. Note that area terms change infrequently ; it may not be necessary to refresh the list of valid areas every time a request is being made for resource information.
Example CURL
curl -X 'GET' \ 'https://directory-uat.mi-cie.org/v1/services/areas' \ -H 'accept: application/json' \ -H 'x-api-key: ZGV2ZWxv******OTg2ODhlMDY4ZGNk' \ -H 'authorization: Bearer eyJraWQiOiJsYmFFa05FR25XbWJ4****sccMLjqZxd_HtCudVAPbqdNS_e_w' Request URL
Response
The following is a sample response. These taxonomy IDs (e.g., BD-1800.2000) can be used to filter the query to only resources that provide certain specific services (e.g., food pantries)
[
{
"id": 196,
"type": "city",
"name": "Grand Rapids",
}
{
"id": 200,
"type": "zipcode",
"name": "49456"
}
]
Filters
zip code filters will return:
all services matched to that specific zip code
all services matched to the city where that zip code resides
all services matched to the county where that zip code resides
services matched to a special region at the zipcode or a larger region including the zipcode
all state wide services
city filters will return:
all services matched to any zip code contained within the city
all services matched to that specific city
all services matched to the county where that city resides
services matched to a special region within the city or a larger region including the city
all state wide services
county filters will return:
all services matched to any zip code contained within the county
all services matched to any city contained within the county
all services matched to that specific county
services matched to a special region within the county or a larger region including the county
all state wide services
Step 3 - Call [GET /services] or [GET /services/complete] with the filter query string parameter.
Now that we have the area, we can create the query.
The area only query can be made against both endpoints. [GET /services] or [GET /services/complete]
To filter only on area the query will be: {"$area": {"type":"zipcode", "name":"49456"}}
Area and Taxonomy term query can be made against both endpoints [GET /services/complete] [GET /services]
Filter area and taxonomy term: {"$area": {"type":"city", "name":"detroit", "$table.field":[{"service_taxonomy.taxonomy_detail": "Tutoring Services"}]}}
Filter area and sub category:{"$area": {"type":"zipcode", "name":"49534", "$table.field":[{"service_taxonomy.subcategory": "Medical Appointments Transportation"}]}}
Filter area and category: {"$area": {"type":"city", "name":"detroit", "$table.field":[{"service_taxonomy.category": "transportation"}]}}
The table.field array can take any number of fields. Services will return that satisfy all conditions within the table.field array. (The table.field array joins conditions with AND, not OR)
Filter area with multiple taxonomy fields: {"$area": {"type":"county", "name":"monroe", "$table.field":[{"service_taxonomy.subcategory": "Medical Appointments Transportation"}, {"service_taxonomy.category": "transportation"}]}}
curl -X 'GET' \ 'https://directory-dev.mi-cie.org/v1/services/complete?query=%7B%22%24area%22%3A%20%5B%7B%22service_taxonomy.taxonomy_id%22%3A%20%22BD-1800.2000%22%7D%2C%20%7B%22physical_address.postal_code%22%3A%20%2249456%22%7D%5D%7D' \ -H 'accept: application/json' \ -H 'x-api-key: ZGV2ZWxvcG1******tOTg2ODhlMDY4ZGNk' \ -H 'authorization: Bearer eyJraWQiOiJsYmFFa05F***hmsrnqPtCIqhR8-gg'
Response
The following is a sample response from the query
[
{
"id": 854,
"organization_id": 1317,
"location_id": 1318,
"source_service_id": "1450",
"program_id": 2261,
"program": "LABORATORY SERVICES",
"name": "CHOLESTEROL/TRIGLYCERIDES TESTS",
"alternate_name": null,
"description": "Offers prompt, courteous service to our patients and offer a wide variety of tests to meet all of your physician's requirements. We can easily accommodate the needs of your physician, whether he/she practices in Allegan or another community, so you do not have to travel out of town to have your lab work done. Provides fast, convenient service to assist medical professionals in diagnosing disease.",
"url": null,
"email": null,
"status": 1,
"interpretation_services": null,
"application_process": "Referral required from physician",
"wait_time": null,
"fees": "Fees vary",
"accreditations": null,
"licenses": null,
"eligibility": "Call for information",
"language": null,
"payment_accepted": "Call for details",
"required_document": "Call for more information",
"service_area": "Michigan",
"region": "GRYP"
},
{
"id": 992,
"organization_id": 2494,
"location_id": 2495,
"source_service_id": "3060",
"program_id": 8652,
"program": "HEALING THE CHILDREN/ MICHIGAN - OHIO",
"name": "HEALTH CARE AND TRANSPORTATION TO INTERNATIONAL CHILDREN IN NEED",
"alternate_name": null,
"description": "Works with liaisons in foreign countries to identify children needing help - medical or surgical care not available in their own country. Provides airfare and secures donated physician and hospital services. Patients are those children who do not qualify for government assistance. The reasons the child is unable to receive care in their home country may vary. The case must meet available resources. Parents do not accompany the child. HTC will send the medical teams to foreign countries upon request.",
"url": null,
"email": null,
"status": 1,
"interpretation_services": null,
"application_process": "Call to apply",
"wait_time": null,
"fees": "No fees",
"accreditations": null,
"licenses": null,
"eligibility": "Children needing medical/surgical care, and unavailable in their own country; must meet available resources.",
"language": "No restriction if a translator can be found. Best to have referral information in English.",
"payment_accepted": "Not applicable",
"required_document": "Call for more information",
"service_area": "Michigan and Ohio",
"region": "MICH"
},
{
"id": 1301,
"organization_id": 2642,
"location_id": 2643,
"source_service_id": "3301",
"program_id": 8655,
"program": "DIRECT CONTACT",
"name": "CRISIS PREGNANCY HOTLINE",
"alternate_name": null,
"description": "Provides information and direct connections through a 24-hour toll free hotline to pregnancy help centers and post-abortion support centers across Michigan.",
"url": null,
"email": null,
"status": 1,
"interpretation_services": null,
"application_process": "Call for more information",
"wait_time": null,
"fees": "No fees",
"accreditations": null,
"licenses": null,
"eligibility": "No restrictions",
"language": null,
"payment_accepted": "Not applicable",
"required_document": "No documentation required",
"service_area": "Michigan",
"region": "MICH"
}
]