Tracks

Create a track

Interacting with the API

The endpoint below is used to create a single track for project with ID project_id.

POST /p-{project_id}/tracks/

Tip: setting the coordinate type of points

This endpoint supports the extra path parameter coordinate_type that allows you to work with local and global coordinates for the track points. Please see API - Setting the Coordinate Type of Points for more information.

The payload of this endpoint includes the following elements:

Element	Type	Unit	Description	Observations
`name`	`string`	-	Name commonly used to identify the track. It can be set to any string	Any name accepted, but must be unique amongst all tracks of a project
`flight_type`	`string`	-	Either arrival or departure	Only accepts `a` for arrivals and `d` for departures
`runway_id`	`int`	-	ID of the runway linked to this track	This runway should belong to the same project where you are creating the track
`points`	`list`	meter / decimal degrees	List of points representing the track	Each point expected as `[x, y]` (local) or `[lat, lon]` (global)

Important when creating a track

Make sure that the runway ID you link to the new track corresponds to a runway that exists and that is part of your project.

Below is an example of how you can create a track for your project.

import requests

def create_track(base_url: str, project_id: int, headers: dict, runway_id: int):

    # Define payload
    track_payload = {
      "name": "My New Track",
      "flight_type": "a",
      "runway_id": runway_id,
      "points": [
          [0, 0],
          [1000, 1000],
          [1000, 2000],
          [2000, 3000]
      ]
    }

    # Choose type of coordinates for the payload
    coordinate = "xy"

    # Create track
    track_response = requests.post(
      f"{base_url}/p-{project_id}/tracks/" + f"?coordinate_type={coordinate}",
      json=track_payload,
      headers=headers
    )

    # Extract response after creating track
    track = track_response.json()

Using the Website

DOCUMENTATION TO BE ADDED SOON

The documentation for this section has not been completed yet.

Upload a track file

The action described in Create a track allows you to add one track at a time to the project. However, for larger projects, you may want to add several tracks at the same time. This is possible by using the endpoint below, which allows you to upload a .csv file that is converted into new tracks. Each row in the file corresponds to a single point.

POST /p-{project_id}/tracks/upload/

Tip: setting the coordinate type of points and grouping file rows

This endpoint supports the extra path parameter coordinate_type that allows you to work with local and global coordinates for the track points. Please see API - Setting the Coordinate Type of Points for more information.

This endpoint also supports another path paramter called group_by. In the cases when your file has more than one track, this paramter allows you to choose which column you want to use to group the rows into a single track. For instance, if your track_name column uniquely identifies a track, you can use it as the group_by column, and Echo will group the rows from the .csv file that share the same track_name into a new track.

Expected columns in file

The columns below should be included in the .csv file you upload to create your tracks. If at least one column is missing, Echo will return a validation error and will let you know which columns are missing.

Column	Type	Unit	Description	Observations
`track_name`	`string`	-	Name of each track	Any name accepted, but must be unique amongst all tracks of a project
`rwy`	`string`	-	Designation of the runway linked to the track	It should match the `designation` field defined in Create a runway
`flight_type`	`string`	-	Either arrival or departure	Only accepts `a` for arrivals and `d` for departures
`x`	`float`	meter	X-coordinate of a single point	-
`y`	`float`	meter	Y-coordinate of a single point	-

Below is an example of how you can upload a file to create several tracks.

from typing import Union
import requests
from pathlib import Path

def upload_tracks_file(base_url: str, project_id: int, headers: dict, file_path: Union[str, Path]):

    # Prepare file
    file = {"file": open(file_path, "rb")}

    # Choose type of coordinates for the payload
    coordinate = "xy"

    # Choose the column used to group the rows into individual tracks
    group_by = "track_name"

    # Upload file
    tracks_response = requests.post(
      f"{base_url}/p-{project_id}/tracks/upload/" + f"?coordinate_type={coordinate}"  + f"&group_by={group_by}",
      files=file,
      headers=headers
    )

    # Extract response after uploading all tracks
    tracks = tracks_response.json()

Using the Website

DOCUMENTATION TO BE ADDED SOON

The documentation for this section has not been completed yet.

Read a track

Interacting with the API

You can read a single track with name track_name from a project with ID project_id by using the endpoint below.

GET /p-{project_id}/tracks/{track_name}/

Tip: setting the coordinate type of points

This endpoint supports the extra path parameter coordinate_type that allows you to work with local and global coordinates for the track points. Please see API - Setting the Coordinate Type of Points for more information.

Besides returning general information about the track, this endpoint also returns its points in the requested coordinate system (global or local). Below is an example of how you can read a single track.

import requests

def read_track(base_url: str, project_id: int, headers: dict, track_name: str):

    # Choose type of coordinates
    coordinate = "xy"

    # Read track
    track_response = requests.get(
      f"{base_url}/p-{project_id}/tracks/{track_name}/" + f"?coordinate_type={coordinate}",
      headers=headers
    )

    # Extract response after fetching track
    track = track_response.json()

Using the Website

DOCUMENTATION TO BE ADDED SOON

The documentation for this section has not been completed yet.

Read all project tracks

Interacting with the API

You can also retrieve information from all tracks that are part of a project with ID project_id. To get this information, the endpoint below can be used.

GET /p-{project_id}/tracks/

Note that, unlike the endpoint that returns a single track, this endpoint will only return the general information of all tracks that are part of this project and will not include each track's points. Below is an example of how you can get a list with information about all tracks from a certain project.

import requests

def read_all_tracks(base_url: str, project_id: int, headers: dict):

    # Read all tracks
    tracks_response = requests.get(
      f"{base_url}/p-{project_id}/tracks/",
      headers=headers
    )

    # Extract response as a list after fetching all tracks
    tracks = tracks_response.json()

Using the Website

DOCUMENTATION TO BE ADDED SOON

The documentation for this section has not been completed yet.

Update a track

Interacting with the API

Once a track is created, only its name can be updated. To make sure the finished calculations that use a certain track remain valid, Echo does not allow to change its points.

To update a track named track_name in a project with ID project_id, the endpoint below is used.

PATCH /p-{project_id}/tracks/{track_name}/

The payload of this endpoint only includes the name field. To get more information about this field, check how to create a track.

Below is an example of how you can update a track's name.

import requests

def update_track(base_url: str, project_id: int, headers: dict, track_name: str):

    # Define payload
    update_payload = {
      "name": "My New Other Track",
    }

    # Update track
    track_response = requests.patch(
      f"{base_url}/p-{project_id}/tracks/{track_name}/",
      json=update_payload,
      headers=headers
    )

    # Extract response after updating track
    track = track_response.json()

Using the Website

DOCUMENTATION TO BE ADDED SOON

The documentation for this section has not been completed yet.

Delete a track

Interacting with the API

To delete a single track with name track_name belonging to a project with ID project_id, the endpoint below can be used.

DELETE /p-{project_id}/tracks/{track_name}/

Deleting a track is an irreversible action

After deleting a track, it is not possible to recover it. Furthermore, all the data linked to that track will also be deleted. You will have to create a new track to replace it.

Below is an example of how you can delete a track.

import requests

def delete_track(base_url: str, project_id: int, headers: dict, track_name: str):

    # Delete track
    track_response = requests.delete(
      f"{base_url}/p-{project_id}/tracks/{track_name}/",
      headers=headers
    )

    # Extract information about deleted track
    track = track_response.json()

Using the Website

DOCUMENTATION TO BE ADDED SOON

The documentation for this section has not been completed yet.