Api reference

components.hp_dataset.public.api

get_entities_by module-attribute

get_entities_by = get_entities_by

get_organization_by_identifier module-attribute

get_organization_by_identifier = (
    get_organization_by_identifier
)

get_organization_by_internal_id module-attribute

get_organization_by_internal_id = (
    get_organization_by_internal_id
)

get_practitioner_by_identifier module-attribute

get_practitioner_by_identifier = (
    get_practitioner_by_identifier
)

get_practitioner_by_internal_id module-attribute

get_practitioner_by_internal_id = (
    get_practitioner_by_internal_id
)

components.hp_dataset.public.controllers

search

HpDatasetPublicSearchEndpoint

Bases: BaseController

Main controller for public search

post

post(search_mode, entity_type)

Search for entities based on filters

Expects a JSON body with SearchRequest structure: { "country": "france", "filters": [...], "text": "optional search text", "text_op": "stemmed", "geolocation": {lat: 48.85, lon: 2.35, radius: 1000}, "geolocation_op": "geo_within_radius", "limit": 10, "offset": 0 }

Source code in components/hp_dataset/public/controllers/search.py

@view_method(
    GlobalAuthorizationStrategies().alaner_admin(
        permitted_for={EmployeePermission.view_hp_dataset}
    )
)
@obs.api_call()
def post(
    self,
    search_mode: str,  # Flask passes URL params as strings
    entity_type: str,  # Flask passes URL params as strings
) -> Response:
    """
    Search for entities based on filters

    Expects a JSON body with SearchRequest structure:
    {
        "country": "france",
        "filters": [...],
        "text": "optional search text",
        "text_op": "stemmed",
        "geolocation": {lat: 48.85, lon: 2.35, radius: 1000},
        "geolocation_op": "geo_within_radius",
        "limit": 10,
        "offset": 0
    }
    """
    # Validate URL parameters and convert to enums
    # EnumValidationError raised on invalid values is caught by Flask
    # and returns a clear error message
    validated_search_mode: SearchMode = SearchMode.validate(search_mode)
    validated_entity_type: EntityType = EntityType.validate(entity_type)

    search_request = SearchRequest(**request.json)  # type:ignore[arg-type]

    results = get_entities_by(
        search_backend=SearchBackend.OPENSEARCH,
        request=search_request,
        entrypoint=validated_entity_type,
        search_mode=validated_search_mode,
    )

    return make_json_response(
        {
            "results": [result.to_dict() for result in results],
        },
        200,
    )

hp_dataset_search_endpoint module-attribute

hp_dataset_search_endpoint = Endpoint('')

components.hp_dataset.public.entities

Organization dataclass

Organization(
    id,
    country,
    displayable_name,
    identifiers,
    properties,
    total_roles=0,
    roles=None,
    parent_organization=None,
    children_organizations=list(),
)

Bases: DataClassJsonMixin

Represents an Organization — a legal entity — in the HP Dataset

children_organizations class-attribute instance-attribute

children_organizations = field(default_factory=list)

country instance-attribute

country

displayable_name instance-attribute

displayable_name

id instance-attribute

id

identifiers instance-attribute

identifiers

parent_organization class-attribute instance-attribute

parent_organization = None

properties instance-attribute

properties

roles class-attribute instance-attribute

roles = None

total_roles class-attribute instance-attribute

total_roles = 0

Practitioner dataclass

Practitioner(
    id,
    country,
    displayable_name,
    identifiers,
    properties,
    total_roles=0,
    roles=None,
)

Bases: DataClassJsonMixin

Represents a Practitioner — an actual human being in the health system — in the HP Dataset

country instance-attribute

country

displayable_name instance-attribute

displayable_name

id instance-attribute

id

identifiers instance-attribute

identifiers

properties instance-attribute

properties

roles class-attribute instance-attribute

roles = None

total_roles class-attribute instance-attribute

total_roles = 0

PractitionerRole dataclass

PractitionerRole(
    id,
    country,
    displayable_name,
    organization,
    practitioner,
    identifiers,
    properties,
)

Bases: DataClassJsonMixin

Represents a PractitionerRole — a link between a Practitioner and an Organization — in the HP Dataset

country instance-attribute

country

displayable_name instance-attribute

displayable_name

id instance-attribute

id

identifiers instance-attribute

identifiers

organization instance-attribute

organization

practitioner instance-attribute

practitioner

properties instance-attribute

properties

Property dataclass

Property(
    id,
    value,
    definition_name,
    definition_value_type,
    source_names,
)

Bases: DataClassJsonMixin

Represents a Property — a value any Practitioner, PractitionerRole or Organization can hold — in the HP Dataset

definition_name instance-attribute

definition_name

definition_value_type instance-attribute

definition_value_type

id instance-attribute

id

source_names instance-attribute

source_names

value instance-attribute

value

components.hp_dataset.public.enums

Country

Bases: AlanBaseEnum

Lists all supported countries by the dataset

BELGIUM class-attribute instance-attribute

BELGIUM = 'be'

CANADA class-attribute instance-attribute

CANADA = 'ca'

FRANCE class-attribute instance-attribute

FRANCE = 'fr'

SPAIN class-attribute instance-attribute

SPAIN = 'es'

DefinitionValueType

Bases: AlanBaseEnum

Lists all possible types of values we can have for a property.

The value_type is understood as an index or generic type, complementing the schema itself that validates the actual content and format of the value.

See https://www.notion.so/alaninsurance/Define-possible-value-types-to-accommodate-various-cases-2141426e8be7805c9ac9c16635abb1ee ⧉

ADDRESS class-attribute instance-attribute

ADDRESS = 'address'

ARRAY class-attribute instance-attribute

ARRAY = 'array'

BOOLEAN class-attribute instance-attribute

BOOLEAN = 'boolean'

CONTACT class-attribute instance-attribute

CONTACT = 'contact'

COSTS class-attribute instance-attribute

COSTS = 'costs'

DATE class-attribute instance-attribute

DATE = 'date'

DATETIME class-attribute instance-attribute

DATETIME = 'datetime'

ENUM class-attribute instance-attribute

ENUM = 'enum'

GEOLOCATION class-attribute instance-attribute

GEOLOCATION = 'geolocation'

HOURS class-attribute instance-attribute

HOURS = 'hours'

IDENTIFIER class-attribute instance-attribute

IDENTIFIER = 'identifier'

SCORE class-attribute instance-attribute

SCORE = 'score'

TEXT class-attribute instance-attribute

TEXT = 'text'

URL class-attribute instance-attribute

URL = 'url'

UUID class-attribute instance-attribute

UUID = 'uuid'

EntityType

Bases: AlanBaseEnum

Lists all possible entities that a property can be linked to

ORGANIZATION class-attribute instance-attribute

ORGANIZATION = 'organization'

PRACTITIONER class-attribute instance-attribute

PRACTITIONER = 'practitioner'

PRACTITIONER_ROLE class-attribute instance-attribute

PRACTITIONER_ROLE = 'practitioner_role'

SearchIntent

Bases: AlanBaseEnum

Lists different intents on the usage of the API

• search: standard intent, we want to search for full entities
• autocomplete: we want a really fast autocomplete flavour, nothing more

AUTOCOMPLETE class-attribute instance-attribute

AUTOCOMPLETE = 'autocomplete'

SEARCH class-attribute instance-attribute

SEARCH = 'search'

SearchMode

Bases: AlanBaseEnum

Lists all possible ways we can retrieve results from an API search

• full: will return the whole entity with its properties
• id_and_name: will only return the id and the displayable name, which is faster since it'll directly come from the actual indexes we're searching in, not from a separate query.

FULL class-attribute instance-attribute

FULL = 'full'

ID_AND_NAME class-attribute instance-attribute

ID_AND_NAME = 'id_and_name'