{"id":30309380,"url":"https://github.com/infermedica/python-api","last_synced_at":"2025-08-17T13:42:42.580Z","repository":{"id":31599114,"uuid":"35163977","full_name":"infermedica/python-api","owner":"infermedica","description":"A Python client for Infermedica API.","archived":false,"fork":false,"pushed_at":"2024-07-29T09:39:42.000Z","size":166,"stargazers_count":56,"open_issues_count":0,"forks_count":30,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-07-26T03:37:57.879Z","etag":null,"topics":["infermedica","infermedica-api","python","python-api"],"latest_commit_sha":null,"homepage":"https://developer.infermedica.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/infermedica.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-06T14:36:58.000Z","updated_at":"2025-07-01T11:29:22.000Z","dependencies_parsed_at":"2024-06-21T13:23:24.580Z","dependency_job_id":null,"html_url":"https://github.com/infermedica/python-api","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/infermedica/python-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infermedica%2Fpython-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infermedica%2Fpython-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infermedica%2Fpython-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infermedica%2Fpython-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infermedica","download_url":"https://codeload.github.com/infermedica/python-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infermedica%2Fpython-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270856582,"owners_count":24657693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["infermedica","infermedica-api","python","python-api"],"created_at":"2025-08-17T13:42:41.769Z","updated_at":"2025-08-17T13:42:42.500Z","avatar_url":"https://github.com/infermedica.png","language":"Python","readme":"Python client for Infermedica API \n=================================\n\nInfermedica Python client provides pragmatical access to a medical diagnostic API created by [Infermedica](http://infermedica.com).\nBefore using the library one must register for a developer account and obtain App-Id and App-Key at [Infermedica Developer Portal](https://developer.infermedica.com). All the API documentation is also available there.\n\n\n# Installation\n\nInstall using `pip`:\n\n```bash\npip install infermedica-api\n```\n\n### Quick start\n\nA Quick verification if all works fine:\n\n```python\nimport infermedica_api\n\napi = infermedica_api.APIv3Connector(app_id=\"YOUR_APP_ID\", app_key=\"YOUR_APP_KEY\")\nprint(api.info())\n```\n\n# Configuration\n\n## API Connectors\nThe library provides several \"API Connectors\", that can be used for communication with the Infermedica API. Depending on the required API version and programmatic integration level, a different API Connector should be used. The connectors can be distinguished by two factors. The first factor is the Infermedica API version. The API version is indicated by the connector class name e.g. `APIv3Connector` or `APIv2Connector`. The second factor is the programmatic integration level.  There are three levels available.\n\nHere is a list of currently available API Connectors:\n* `BasicAPIv3Connector` - API version: \"v3\", Integration level: \"Basic\"\n* `APIv3Connector` - API version: \"v3\", Integration level: \"Standard\" _(default, recommended)_\n* `BasicAPIv2Connector` - API version: \"v2\", Integration level: \"Basic\"\n* `APIv2Connector` - API version: \"v2\", Integration level: \"Standard\"\n* `ModelAPIv2Connector` - API version: \"v2\", Integration level: \"Model\"\n\n### Basic Connectors\nProvides all Infermedica API capabilities as methods, but all methods expose low level HTTP parameters e.g. query params, data or headers. This type of connector should be used if one needs to have full control over the underlying HTTP request content. Each basic connector class is prefixed with \"Basic\" keyword, e.g. `BasicAPIv3Connector` or `BasicAPIv2Connector`.\n\nHere is an example to illustrate the basic connector method signature:\n```python\ndef diagnosis(data, params=None, headers=None) -\u003e Dict: ...\n```\n\n### Standard Connectors\n_(default, recommended)_\n\nStandard Connectors are based on Basic Connectors, but provide methods with more detailed attribute signatures. At the same time they operate on basic Python data types like `dict`, `list` or `string`. Therefore, it is easier to understand what is required for each method, and they take care of constructing proper a request to Infermedica API. The standard API connectors do not have s prefix in the class name e.g. `APIv3Connector` or `APIv2Connector`. It is the default and recommended level of integration.\n\nHere is an example to illustrate standard connector method signature:\n```python\ndef diagnosis(evidence, sex, age, age_unit=None, extras=None, interview_id=None) -\u003e Dict: ...\n```\n\n### Model Connectors\n\nModel Connectors are even higher level connectors, that are based on Standard Connectors. They expose methods that operate on predefined model classes as their inputs and outputs. Each model connector class is prefixed with the \"Model\" keyword, e.g. `ModelAPIv2Connector`.\n\nHere is an example to illustrate model connector method signature:\n```python\ndef diagnosis(diagnosis_request: Diagnosis) -\u003e Diagnosis: ...\n```\n\n\n## Configuration types\nThere are two options to configure the API module, one may choose the most suitable option for related project.\n\n### Local Configuration\nSingle local API Connector.\n\n```python\nimport infermedica_api\n\napi = infermedica_api.APIv3Connector(app_id=\"YOUR_APP_ID\", app_key=\"YOUR_APP_KEY\")\n\nprint(api.info())\n```\n\nEach API Connector constructor takes several configuration parameters, among others:\n* `app_id` \u0026 `app_key` - Infermedica API credentials, the only two mandatory arguments.\n* `model` - Infermedica API language model to be used, [see the docs](https://developer.infermedica.com/docs/v3/basics#models).\n* `dev_mode` - Flag that indicates if requests are made on local or testing environment and are not real medical cases.\n\n\n### Global Configuration\nConfiguration of one or many global API Connectors, that are easily available everywhere. For this purpose the `configure` function has to be used, to register global configurations. The configuration should be done in a place of the project that is executed on project startup, e.g. in some `__init__.py` file.\n\nThe `configure` function takes exactly the same parameters as each API Connector class constructor, but expect few additional optional parameters:\n* `alias` - A unique string identifier of the configuration, if not provided configuration is registered as default.\n* `default` - In case `alias` is provided, this flag determinate if the configuration should be also registered as the default one. There may be only one default.\n* `api_connector` - API connector class to be used for the configuration or just a string with API Connector name, e.g. `\"APIv3Connector\"` _(default)_\n\nTo define a single global connector:\n\n```python\nimport infermedica_api\n\ninfermedica_api.configure(app_id=\"YOUR_APP_ID\", app_key=\"YOUR_APP_KEY\")\n```\n\nTo define multiple global connectors:\n\n```python\nimport infermedica_api\n\n# Aliased, default configuration with English language\ninfermedica_api.configure(\n    alias=\"en\",\n    default=True,\n    app_id=\"YOUR_APP_ID\",\n    app_key=\"YOUR_APP_KEY\",\n    model=\"infermedica-en\"\n)\n\n# Configuration with Polish language\ninfermedica_api.configure(\n    alias=\"pl\",\n    app_id=\"YOUR_APP_ID\",\n    app_key=\"YOUR_APP_KEY\",\n    model=\"infermedica-pl\"\n)\n\n# Configuration with English language based on non-default connector\ninfermedica_api.configure(\n    alias=\"basic-en\",\n    app_id=\"YOUR_APP_ID\",\n    app_key=\"YOUR_APP_KEY\",\n    model=\"infermedica-en\",\n    api_connector=infermedica_api.BasicAPIv3Connector\n)\n```\n\n... and then at any place in the project just import the infermedica module and get an already configured API connector through `get_api` function:\n\n```python\nimport infermedica_api\n\napi = infermedica_api.get_api()  # Get default connector\nprint(api.info())\n\napi = infermedica_api.get_api(\"pl\")  # Get connector by alias\nprint(api.info())\n```\n\n# Usage\n\nHere is an example of how to use the API to get a list of patient's likely conditions.\n\n```python\nimport infermedica_api\n\napi = infermedica_api.APIv3Connector(app_id=\"YOUR_APP_ID\", app_key=\"YOUR_APP_KEY\")\n\n# Prepare initial patients diagnostic information.\nsex = \"female\"\nage = 32\nevidence = [\n    {\"id\": \"s_21\", \"choice_id\": \"present\", \"source\": \"initial\"},\n    {\"id\": \"s_98\", \"choice_id\": \"present\", \"source\": \"initial\"},\n    {\"id\": \"s_107\", \"choice_id\": \"present\"}\n]\n\n# call diagnosis\nresponse = api.diagnosis(evidence=evidence, sex=sex, age=age)\n\n# Access question asked by API\nprint(response[\"question\"])\nprint(response[\"question\"][\"text\"])  # actual text of the question\nprint(response[\"question\"][\"items\"])  # list of related evidence with possible answers\nprint(response[\"question\"][\"items\"][0][\"id\"])\nprint(response[\"question\"][\"items\"][0][\"name\"])\nprint(response[\"question\"][\"items\"][0][\"choices\"])  # list of possible answers\nprint(response[\"question\"][\"items\"][0][\"choices\"][0][\"id\"])  # answer id\nprint(response[\"question\"][\"items\"][0][\"choices\"][0][\"label\"])  # answer label\n\n# Check the \"should_stop\" flag\nprint(response[\"should_stop\"])\n\n# Next update the request and get next question:\nevidence.append({\n    \"id\": response[\"question\"][\"items\"][0][\"id\"],\n    \"choice_id\": response[\"question\"][\"items\"][0][\"choices\"][0][\"id\"]  # Just example, the choice_id shall be taken from the real user answer\n})\n\n# call diagnosis method again\nresponse = api.diagnosis(evidence=evidence, sex=sex, age=age)\n\n# ... and so on, continue the interview and watch for the \"should_stop\" flag. \n# Once the API returns a \"should_stop\" flag with the value set to true, the interview questions should stop and you can present the condition results:\n\n# Access list of conditions with probabilities\nprint(response[\"conditions\"])\nprint(response[\"conditions\"][0][\"id\"])\nprint(response[\"conditions\"][0][\"name\"])\nprint(response[\"conditions\"][0][\"probability\"])\n```\n\n\n## Examples\n\nTo see more use cases on how to use the library look at the examples provided. One can easily check out and run examples, first define environmental variables with credentials then run the selected example:\n\n ```bash\nexport APP_ID=\u003cYOUR_APP_ID\u003e\nexport APP_KEY=\u003cYOUR_APP_KEY\u003e\n\npython -m examples.v3.search\npython -m examples.v3.parse\npython -m examples.v3.symptoms\npython -m examples.v3.risk_factors\npython -m examples.v3.conditions\npython -m examples.v3.lab_tests\npython -m examples.v3.concepts\npython -m examples.v3.diagnosis\npython -m examples.v3.explain\npython -m examples.v3.triage\npython -m examples.v3.suggest\npython -m examples.v3.specialist_recommender\n```\n\n## Exceptions\n\nThe library provides its own set of exceptions. Here is a list of exceptions, that are related to network communication and account permissions, which can be raised on any of the API Connector method calls:\n\n```\ninfermedica_api.exceptions.BadRequest\ninfermedica_api.exceptions.UnauthorizedAccess\ninfermedica_api.exceptions.ForbiddenAccess\ninfermedica_api.exceptions.ResourceNotFound\ninfermedica_api.exceptions.MethodNotAllowed\ninfermedica_api.exceptions.ServerError\ninfermedica_api.exceptions.ConnectionError\n```\n\nThere are also few additional exception that may occur:\n\n* `MissingConfiguration` is raised during the `get_api` call if the API configuration for a given alias was not registered. Or the default API has not been configured, while calling `get_api` without the alias parameter.\n* `MethodNotAvailableInAPIVersion` is raised if one tries to use a method from different API version.\n* `InvalidSearchConceptType` is raised when the wrong filters are provided to the `search` method.\n* `InvalidConceptType` is raised when the wrong concept types are provided to the `concepts` method.\n* `InvalidAgeUnit` is raised when the wrong age unit is provided in API v3 Connectors.\n\n\n# Contributing\n\nArkadiusz Szydełko ([akszydelko](https://github.com/akszydelko)) and Paweł Iwaszko ([iwaszko](https://github.com/iwaszko)) are the creators and current maintainers of the Infermedica API Python client. \n\nPull requests are always welcome. Before submitting a pull request, please ensure that your coding style follows PEP 8 and rules form `.editorconfig` file. Also note that the library if formatted according to `black` rules so please apply them.\n\n# Legal\n\nCopyright 2024 by [Infermedica](http://infermedica.com).\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfermedica%2Fpython-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfermedica%2Fpython-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfermedica%2Fpython-api/lists"}