HSDA Taxonomy

The HSDA taxonomy protocol is defined by openapi-hsda-taxonomy.yaml. The details below show the available methods and responses.

This is a separate HSDA service for working with taxonomy across all the core human services resources, support any categorization or taxonomy, and allowing for filtering of services by taxonomy.

You can also explore this using our OpenAPI viewer.

Warning

This is an experimental feature. Feedback is welcome to shape its further development.

GET /taxonomy/

Get Taxonomy

Get Taxonomy

Status Codes:

200 Response Body:

  Description Type Required
id
  Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them. string True
name
  The name of this taxonomy term or category. string True
parent_id
  If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank. string False
parent_name
  If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank. string False
vocabulary
  If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility. string False
POST /taxonomy/

Add taxonomy

Addtaxonomy

Status Codes:

200 Response Body:

  Description Type Required
id
  Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them. string True
name
  The name of this taxonomy term or category. string True
parent_id
  If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank. string False
parent_name
  If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank. string False
vocabulary
  If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility. string False
GET /taxonomys/{taxonomy_id}/

Get Taxonomy

Get Taxonomy

Parameters:
  • taxonomy_id (string) -- The taxonomy id.
Status Codes:

200 Response Body:

  Description Type Required
id
  Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them. string True
name
  The name of this taxonomy term or category. string True
parent_id
  If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank. string False
parent_name
  If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank. string False
vocabulary
  If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility. string False
PUT /taxonomys/{taxonomy_id}/

Update Taxonomy

Update Taxonomy

Parameters:
  • taxonomy_id (string) -- The unique taxonomy id.
Status Codes:

200 Response Body:

  Description Type Required
id
  Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them. string True
name
  The name of this taxonomy term or category. string True
parent_id
  If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank. string False
parent_name
  If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank. string False
vocabulary
  If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility. string False
DELETE /taxonomys/{taxonomy_id}/

Delete Taxonomy

Delete Taxonomy

Parameters:
  • taxonomy_id (string) -- The taxonomy id.
Status Codes:

200 Response Body:

  Description Type Required
id
  Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them. string True
name
  The name of this taxonomy term or category. string True
parent_id
  If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank. string False
parent_name
  If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank. string False
vocabulary
  If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility. string False
GET /services/{taxonomy_name}/

Get Services

Get Services

Parameters:
  • taxonomy_name (string) -- The taxonomy name.
Query Parameters:
 
  • query (string) -- A query to filter list by (up to provider to determine what to search)
  • queries (string) -- A comma separate list of queries with specific fields.
  • page (number) -- The particular page of results.
  • per_page (number) -- Number of records return per page, up to 100.
  • sort_by (string) -- Which field to sort by.
  • order (string) -- Which order to sort by (asc,desc).
Status Codes:

200 Response Body:

  Description Type Required
id
  Each service must have a unique identifier. string False
organization_id
  The identifier of the organization that provides this service. string False
program_id
  The identifier of the program this service is delivered under. string False
location_id
  The identifier of the location where this service is delivered. string False
name
  The official or public name of the service. string False
alternate_name
  Alternative or commonly used name for a service. string False
description
  A description of the service. string False
url
  URL of the service. string False
email
  Email address for the service. string False
status
  The current status of the service. string False
interpretation_services
  A description of any interpretation services available for accessing this service. string False
application_process
  The steps needed to access the service. string False
wait_time
  Time a client may expect to wait before receiving a service. string False
fees
  Details of any charges for service users to access this service. string False
accreditations
  Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization. string False
licenses
  An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here. string False
GET /services/complete/{taxonomy_name}/

Get Services (Complete)

Get Services (Complete)

Parameters:
  • taxonomy_name (string) -- The taxonomy name.
Query Parameters:
 
  • query (string) -- A query to filter list by (up to provider to determine what to search)
  • queries (string) -- A comma separate list of queries with specific fields.
  • page (number) -- The particular page of results.
  • per_page (number) -- Number of records to return per page, up to 100.
  • sort_by (string) -- Which field to sort by.
  • order (string) -- Which order to sort by (asc,desc).
Status Codes:

200 Response Body:

  Description Type Required
id
  Each service must have a unique identifier. string True
organization_id
  The identifier of the organization that provides this service. string True
program_id
  The identifier of the program this service is delivered under. string False
location_id
  The identifier of the location where this service is delivered. string False
name
  The official or public name of the service. string True
alternate_name
  Alternative or commonly used name for a service. string False
description
  A description of the service. string False
url
  URL of the service. string False
email
  Email address for the service. string False
status
  The current status of the service. string True
interpretation_services
  A description of any interpretation services available for accessing this service. string False
application_process
  The steps needed to access the service. string False
wait_time
  Time a client may expect to wait before receiving a service. string False
accreditations
  Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization. string False
licenses
  An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here. string False
contacts/0/id
  Each contact must have a unique identifier. string True
contacts/0/organization_id
  The identifier of the organization for which this is a contact. string False
contacts/0/service_id
  The identifier of the service for which this is a contact. string False
contacts/0/service_at_location_id
  The identifier of the ‘service at location’ table entry, when this contact is specific to a service in a particular location. string False
contacts/0/name
  The name of the person. string False
contacts/0/title
  The job title of the person. string False
contacts/0/department
  The department that the person is part of. string False
contacts/0/email
  The email address of the person. string False
eligibility/0/id
  Each entry must have a unique identifier. string True
eligibility/0/service_id
  The identifier of the service for which this entry describes the eligibility criteria. string False
eligibility/0/eligibility
  The rules or guidelines that determine who can receive the service. string False
fees/0/id
  Each entry must have a unique identifier. string True
fees/0/service_id
  The identifier of the service for which this entry describes the costs of service. string False
fees/0/fee
  A listing of the costs of services, including free ones. string False
funding/0/id
  Each entry must have a unique identifier. string True
funding/0/organization_id
  The identifier of the organization for which this entry describes the source of funding. string False
funding/0/service_id
  The identifier of the service for which this entry describes the source of funding. string False
funding/0/source
  Source of funds for organization or service. string False
regular_schedule/0/id
  Each entry must have a unique identifier. string True
regular_schedule/0/service_id
  The identifier of the service for which this is the regular schedule. string False
regular_schedule/0/location_id
  The identifier of the location for which this is the regular schedule. string False
regular_schedule/0/service_at_location_id
  The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location. string False
regular_schedule/0/weekday
  The day of the week that this entry relates to. string True
regular_schedule/0/opens_at
  The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time. string False
regular_schedule/0/closes_at
  The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time. string False
holiday_schedule/0/id
  Each entry must have a unique identifier. string True
holiday_schedule/0/service_id
  The identifier of the service for which this is the holiday schedule. string False
holiday_schedule/0/location_id
  The identifier of the location for which this is the holiday schedule. string False
holiday_schedule/0/service_at_location_id
  The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location. string False
holiday_schedule/0/closed
  Indicates if a service or location is closed during a public holiday. boolean True
holiday_schedule/0/opens_at
  The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time. string False
holiday_schedule/0/closes_at
  The time when a service or location closes. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time. string False
holiday_schedule/0/start_date
  The first day that a service or location is closed during a public or private holiday. string True
holiday_schedule/0/end_date
  The last day that a service or location is closed during a public or private holiday. string True
languages/0/id
  Each language must have a unique identifier. string True
languages/0/service_id
  The identifier of the service for which the entry describes the languages in which services are delivered. string False
languages/0/location_id
  The identifier of the location for which the entry describes the languages in which services are delivered. string False
languages/0/language
  Languages, other than English, in which the service is delivered. Languages are listed as ISO639-1 codes.. string False
payment_accepted/0/id
  Each entry must have a unique identifier. string True
payment_accepted/0/service_id
  The identifier of the services for which the entry describes the accepted payment methods. string False
payment_accepted/0/payment
  The methods of payment accepted for the service. string False
phones/0/id
  Each entry must have a unique identifier. string True
phones/0/location_id
  The identifier of the location where this phone number is located. string False
phones/0/service_id
  The identifier of the service for which this is the phone number. string False
phones/0/organization_id
  The identifier of the organisation for which this is the phone number. string False
phones/0/contact_id
  The identifier of the contact for which this is the phone number. string False
phones/0/service_at_location_id
  The identifier of the ‘service at location’ table entry, when this phone number is specific to a service in a particular location. string False
phones/0/number
  The phone number. string True
phones/0/extension
  The extension of the phone number. string False
phones/0/type
  Whether the phone number relates to a fixed or cellular phone. string False
phones/0/department
  The department for which this is the phone number. string False
phones/0/language
  A comma separated list of ISO 639-1, or ISO 639-2 language codes to represent the languages available from this phone service. The three-letter codes from ISO 639-2 provide greater accuracy when describing variants of languages, which may be relevant to particular communities. string False
phones/0/description
  A description providing extra information about the phone service (e.g. any special arrangements for accessing, or details of availability at particular times. string False
required_documents/0/id
  Each document must have a unique identifier. string True
required_documents/0/service_id
  The identifier of the service for which this entry describes the required document. string False
required_documents/0/document
  The document required to apply for or receive the service. e.g. Government-issued ID, EU Passport. string False
service_area/0/id
  Each service area must have a unique identifier. string True
service_area/0/service_id
  The identifier of the service for which this entry describes the service area. string False
service_area/0/service_area
  The geographic area where a service is available. This is a free-text description, and so may be precise or indefinite as necessary. string False
service_area/0/description
  A more detailed description of this service area. Used to provide any additional information that cannot be communicated using the structured area and geometry fields. string False