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