API Template usage cheatsheet: Difference between revisions

From Tygron Preview Support Wiki
Jump to navigation Jump to search
← Older edit
No edit summary
mNo edit summary
 
(14 intermediate revisions by the same user not shown)
Line 15: Line 15:
|image=
|image=
|table=
|table=
; Any url starting with /api/
  {{{!}}
: HTTP Basic Authentication Header
  ! URL starts with !! Description!! Example
: "Authorization: Basic " + base64encode("username@example.com:password")
  {{!}}-
; Any url starting with /api/session/
  {{!}} /api/ {{!}}{{!}} HTTP Basic Authentication Header {{!}}{{!}} "Authorization: Basic "+b64en("user@example.com:password")
: API token query parameter in url
  {{!}}-
: "/api/session/items/neighborhoods?f=JSON&token=[...]"
  {{!}} /api/session/ {{!}}{{!}} API token query parameter {{!}}{{!}} "/api/session/items/neighborhoods?f=JSON&token=[...]"
; Any url starting with /web/
  {{!}}-
: Web token query parameter in url (API token is also allowed)
  {{!}} /web/ {{!}}{{!}} Web (or API) token query parameter {{!}}{{!}} "/api/web/2dmap.html?f=JSON&token=[...]"
: "/api/web/2dmap.html?f=JSON&token=[...]"
  {{!}}}
}}
}}


Line 29: Line 29:
|title=Applying a Template project
|title=Applying a Template project
|type=parameters
|type=parameters
|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:  
|text=Use "demo heat stress" to create a new Project named "my_project", and get its API Token:  
|image=
|image=
|table=
|table=
   {{{!}}
   {{{!}}
   ! Method !! !! Parameters !! Response
   ! !! URL !! Parameters !! Response
   {{!}}-
   {{!}}-
   {{!}} POST {{!}}{{!}} /api/io/start/?f=JSON {{!}}{{!}} ["EDITOR", "demo_heat_stress"] {{!}}{{!}} sessionId
   {{!}} POST {{!}}{{!}} /api/io/start/ {{!}}{{!}} ["EDITOR", "demo_heat_stress"] {{!}}{{!}} sessionId
   {{!}}-
   {{!}}-
   {{!}} POST {{!}}{{!}} /api/io/save_project_as/?f=JSON {{!}}{{!}} [''sessionId'', "","my_project",false] {{!}}{{!}} Whether succesful
   {{!}} POST {{!}}{{!}} /api/io/save_project_as/ {{!}}{{!}} [''sessionId'', "","my_project",false] {{!}}{{!}} Whether succesful
   {{!}}-
   {{!}}-
   {{!}} POST {{!}}{{!}} /api/io/join/?f=JSON {{!}}{{!}} [''sessionId'', "EDITOR"] {{!}}{{!}} json, including apiToken
   {{!}} POST {{!}}{{!}} /api/io/join/ {{!}}{{!}} [''sessionId'', "EDITOR"] {{!}}{{!}} json, including apiToken
   {{!}}}
   {{!}}}
}}
}}
Line 46: Line 46:
|title=Generate on new location
|title=Generate on new location
|type=parameters
|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 ):
|text=Set new Project to a 2km by km map size, and its location to latitude 52.080617, longitude 4.312135 (in coordinate system EPSG:4326 ):
|image=
|image=
|table=
|table=
   {{{!}}
   {{{!}}
   ! Method !! URL !! Parameters !! Response
   ! !! URL !! Parameters !! Response
   {{!}}-
   {{!}}-
   {{!}} POST {{!}}{{!}} api/session/event/editor/clear_map/?f=JSON {{!}}{{!}} [true] {{!}}{{!}} n/a
   {{!}} POST {{!}}{{!}} api/session/event/editor/clear_map/ {{!}}{{!}} [true] {{!}}{{!}} n/a
   {{!}}-
   {{!}}-
   {{!}} POST {{!}}{{!}} /api/session/event/editor/set_initial_map_size/?f=JSON {{!}}{{!}} [2000,2000] {{!}}{{!}} n/a
   {{!}} POST {{!}}{{!}} /api/session/event/editor/set_initial_map_size/ {{!}}{{!}} [2000,2000] {{!}}{{!}} n/a
   {{!}}-
   {{!}}-
   {{!}} POST {{!}}{{!}} api/session/event/editor/start_map_creation?f=JSON {{!}}{{!}} [52.080617, 4.312135, false, []] {{!}}{{!}} n/a
   {{!}} POST {{!}}{{!}} api/session/event/editor/start_map_creation?crs=4326 {{!}}{{!}} [4.312135, 52.080617, null, []] {{!}}{{!}} n/a
  {{!}}-
  {{!}} GET {{!}}{{!}} /api/session/info/ {{!}}{{!}} {{!}}{{!}} json, including state.<br> "NORMAL" means<br>generation is done
  {{!}}}
}}
 
{{cheatsheet-block
|title=Get results
|type=results
|text=
|image=
|table=
  {{{!}}
  ! Data !! Calculation
   {{!}}-
   {{!}}-
   {{!}} GET {{!}}{{!}} /api/session/info/?f=JSON {{!}}{{!}} {{!}}{{!}} json, including state.<br> "NORMAL" means generation is done
   {{!}}
* /api/session/wfs/
* /api/session/items/neighborhoods?f=GEOJSON
* /api/session/items/areas?f=GEOJSON
  {{!}}{{!}}
* /web/wms/
* /api/session/overlay.png?id=''overlayId''
* /api/session/overlay.geotiff?id=''overlayId''
* /web/indicator.html?id=''indicatorId''
   {{!}}}
   {{!}}}
}}
}}
{{cheatsheet-block
{{cheatsheet-block
|title=Notes
|title=Notes
Line 66: Line 88:
|image=
|image=
|text=<nowiki></nowiki>
|text=<nowiki></nowiki>
* Unless otherwise specified, calls should be accompanied with a query parameter "&f=JSON", to define JSON as the used datastructure in data and responses.
* 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]].
* 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.
* All coordinates are x:y, or longitude:latitude. 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.
* To add an Area of Interest, in the "start_map_creation" event replace the empty array with an array of MultiPolygons.
}}
}}


}}
}}

Latest revision as of 06:41, 3 April 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

URL starts with Description Example
/api/ HTTP Basic Authentication Header "Authorization: Basic "+b64en("user@example.com:password")
/api/session/ API token query parameter "/api/session/items/neighborhoods?f=JSON&token=[...]"
/web/ Web (or API) token query parameter "/api/web/2dmap.html?f=JSON&token=[...]"


Applying a Template project

Use "demo heat stress" to create a new Project named "my_project", and get its API Token:

URL Parameters Response
POST /api/io/start/ ["EDITOR", "demo_heat_stress"] sessionId
POST /api/io/save_project_as/ [sessionId, "","my_project",false] Whether succesful
POST /api/io/join/ [sessionId, "EDITOR"] json, including apiToken


Generate on new location

Set new Project to a 2km by km map size, and its location to latitude 52.080617, longitude 4.312135 (in coordinate system EPSG:4326 ):

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


Get results
Data Calculation
  • /api/session/wfs/
  • /api/session/items/neighborhoods?f=GEOJSON
  • /api/session/items/areas?f=GEOJSON
  • /web/wms/
  • /api/session/overlay.png?id=overlayId
  • /api/session/overlay.geotiff?id=overlayId
  • /web/indicator.html?id=indicatorId


Notes

  • Unless otherwise specified, calls should be accompanied with a query parameter "&f=JSON", to define JSON as the used datastructure in data and responses.
  • 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:latitude. 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=62152"