API Template usage cheatsheet: Difference between revisions

From Tygron Preview Support Wiki
Jump to navigation Jump to search
Newer edit →
Created page with "{{cheatsheet|columns=2| {{cheatsheet-block |title=Core principles |type=description |text= The {{software}} allows for Projects to be used as Templates. Applying them to a new location, carrying over their calculation models and configurations, means its possible to rapidly apply identical analyses. Using the API, this process can be fully automated. |image= |table= }} {{cheatsheet-block |title=Applying a Template project |type=parameters |text..."
 
No edit summary
Line 1: Line 1:
{{cheatsheet|columns=2|
{{cheatsheet|columns=1|


{{cheatsheet-block
{{cheatsheet-block
Line 7: Line 7:
|image=
|image=
|table=
|table=
}}
{{cheatsheet-block
|title=Authentication
|type=paramameters
|text=Every API call must be accompanied with an appropriate form of authentication
|image=
|table=
; Any url starting with /api/
: HTTP Basic Authentication Header
: "Authorization: Basic " + base64encode("username@example.com:password")
; Any url starting with /api/session/
: API token query parameter in url
: "/api/session/items/neighborhoods?f=JSON&token=[...]"
; Any url starting with /web/
: Web token query parameter in url (API token is also allowed)
: "/api/web/2dmap.html?f=JSON&token=[...]"
}}
}}


Line 12: Line 29:
|title=Applying a Template project
|title=Applying a Template project
|type=parameters
|type=parameters
|text= Any [[Project]] can be used as a Template, as long as there is no currently running [[Session]], or the [[Project]] is set to [[read-only]].
|text=To use a template named "demo heat stress" to create a new Project named "my_project", and get its API token for further operations:
|datatype= Root API (/api/)
|image=
|image=
|table=
|table=
; /api/io/start
  {{{!}}
; ['EDITOR', PROJECT_TO_START]
  ! Method !! !! Parameters !! Response
: Start a project
  {{!}}-
   }}
  {{!}} POST {{!}}{{!}} /api/io/start/?f=JSON {{!}}{{!}} ["EDITOR", "demo_heat_stress"] {{!}}{{!}} sessionId
  {{!}}-
  {{!}} POST {{!}}{{!}} /api/io/save_project_as/?f=JSON {{!}}{{!}} [''sessionId'', "","my_project",false] {{!}}{{!}} Whether succesful
  {{!}}-
  {{!}} POST {{!}}{{!}} /api/io/join/?f=JSON {{!}}{{!}} [''sessionId'', "EDITOR"] {{!}}{{!}} json, including apiToken
  {{!}}}
}}
 
{{cheatsheet-block
|title=Generate on new location
|type=parameters
|text=To have a new Project become geographically unreferenced, be set to a 2km by km mapsize, and applied to location with latitude 52.080617, longitude 4.312135 (in coordinate system EPSG:4326 ):
|image=
|table=
  {{{!}}
  ! Method !! URL !! Parameters !! Response
  {{!}}-
  {{!}} POST {{!}}{{!}} api/session/event/editor/clear_map/?f=JSON {{!}}{{!}} [true] {{!}}{{!}} n/a
   {{!}}-
  {{!}} POST {{!}}{{!}} /api/session/event/editor/set_initial_map_size/?f=JSON {{!}}{{!}} [2000,2000] {{!}}{{!}} n/a
  {{!}}-
  {{!}} POST {{!}}{{!}} api/session/event/editor/start_map_creation?f=JSON {{!}}{{!}} [52.080617, 4.312135, false, []] {{!}}{{!}} n/a
  {{!}}-
  {{!}} GET {{!}}{{!}} /api/session/info/?f=JSON {{!}}{{!}} {{!}}{{!}} json, including state.<br> "NORMAL" means generation is done
  {{!}}}
}}
{{cheatsheet-block
|title=Notes
|type=notes
|image=
|text=<nowiki></nowiki>
* Any [[Project]] can be used as a Template, as long as there is no currently running [[Session]], or the [[Project]] is set to [[read-only]].
* All coordinates are x:y, or longitude:latitute. This also includes coordinates in MultiPolygons.
* To add an Area of Interest, in the "start_map_creation" event replace the empty array with an array of MultiPolygons.
}}


}}
}}

Revision as of 13:29, 27 March 2025


Core principles

The Tygron Platform allows for Projects to be used as Templates. Applying them to a new location, carrying over their calculation models and configurations, means its possible to rapidly apply identical analyses. Using the API, this process can be fully automated.


Authentication

Every API call must be accompanied with an appropriate form of authentication

Any url starting with /api/
HTTP Basic Authentication Header
"Authorization: Basic " + base64encode("username@example.com:password")
Any url starting with /api/session/
API token query parameter in url
"/api/session/items/neighborhoods?f=JSON&token=[...]"
Any url starting with /web/
Web token query parameter in url (API token is also allowed)
"/api/web/2dmap.html?f=JSON&token=[...]"


Applying a Template project

To use a template named "demo heat stress" to create a new Project named "my_project", and get its API token for further operations:

Method Parameters Response
POST /api/io/start/?f=JSON ["EDITOR", "demo_heat_stress"] sessionId
POST /api/io/save_project_as/?f=JSON [sessionId, "","my_project",false] Whether succesful
POST /api/io/join/?f=JSON [sessionId, "EDITOR"] json, including apiToken


Generate on new location

To have a new Project become geographically unreferenced, be set to a 2km by km mapsize, and applied to location with latitude 52.080617, longitude 4.312135 (in coordinate system EPSG:4326 ):

Method URL Parameters Response
POST api/session/event/editor/clear_map/?f=JSON [true] n/a
POST /api/session/event/editor/set_initial_map_size/?f=JSON [2000,2000] n/a
POST api/session/event/editor/start_map_creation?f=JSON [52.080617, 4.312135, false, []] n/a
GET /api/session/info/?f=JSON json, including state.
"NORMAL" means generation is done
Notes

  • Any Project can be used as a Template, as long as there is no currently running Session, or the Project is set to read-only.
  • All coordinates are x:y, or longitude:latitute. This also includes coordinates in MultiPolygons.
  • To add an Area of Interest, in the "start_map_creation" event replace the empty array with an array of MultiPolygons.


Retrieved from "https://previewsupport.tygron.com/w/index.php?title=API_Template_usage_cheatsheet&oldid=62131"