Make API docs more clear and easier to use

[aawiseman]

Is your feature request related to a problem? Please describe. These are valuable tools to get information that cannot be retrieved easily from the Tasking Manager.

They are quite technical, in the development sense of the word. There is documentation, but only in a very sparse way.

Describe the solution you'd like Create some more elaborate documentation that could help less technical users also use it.

Or write a few scripts handling the most popular use cases of the API that make them more accessible/usable for non technical users.

Additional context This was Martien's suggestion

[Florence-Njeri]

@petya-kangalova can I take this up?

[petya-kangalova]

@Florence-Njeri that is a good suggestion! @ramyaragupathy let me know if you agree for @Florence-Njeri to work on improving the API docs: https://tasks.hotosm.org/api-docs

[ramyaragupathy]

Sure, please go ahead @Florence-Njeri

[jarmokivekas]

I've worked a fair bit with the TM API in my own standalone tools (not part of the tasking manager). I have some boilerplate examples that I have saved for myself to use. They are in the form of Python scripts written as Jupyter notebooks.

I think these examples could be appropriate for this issue:

• project-geometries-by-organisation-id
• TM4-1-basic-search-summary.ipynb
• TM4-2-campaign-status-report.ipynb
• TM4-3-project-users-activity.ipynb
• TM4-authenticated-api-endpoints.ipynb
• TM4-conributions.ipynb

I've also sometimes used the API embedded into a Google Sheets spreadsheet in a way that automatically updates data in the spreadsheet via the API. My notes for how to do that are here:

• tm-project-status-in-google-sheets.md

Feel free to use and adapt any material in that repository as you see fit :)