Get Locations

URL

GET https://api.magicrail.io/locations

Description

This endpoint allows for the retrieval of standalone location data for the authenticated user based on various search criteria.

Authentication

Bearer Token required

Headers

Ensure these headers are included in the request.

• Content-Type: application/json
• Authorization: Bearer TOKEN

Query Parameters

Provide the optional query parameters to filter the location data.

• start: timestamp with time zone - Start time for the range filter.
• end: timestamp with time zone - End time for the range filter.
• north: double precision - Northern latitude boundary for bounding box filter.
• south: double precision - Southern latitude boundary for bounding box filter.
• east: double precision - Eastern longitude boundary for bounding box filter.
• west: double precision - Western longitude boundary for bounding box filter.
• lat: double precision - Latitude for proximity filter.
• lon: double precision - Longitude for proximity filter.
• radius: string - Radius around the specified point for proximity filter (e.g., "10km").
• elevation_min: double precision - Minimum elevation for elevation range filter.
• elevation_max: double precision - Maximum elevation for elevation range filter.
• metadata: JSON object - Key-value pairs to filter locations based on metadata.
• metadata_key: string - Specific metadata key presence filter.
• activity: string - Activity type filter.

Success Response

Description of a successful attempt to retrieve location data.

• 🟢 200 OK: Successfully retrieved location data.

Error Responses

Descriptions of common error responses.

• 🔴 400 Bad Request: Bad request or authentication error.
• 🔴 500 Internal Server Error: Internal server error.

Example Call and Response

An example showing how to make a request and an example response.

Example Call:

Time Range Filter

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer TOKEN" \
     "https://api.magicrail.io/locations?start=2024-07-01T00:00:00Z&end=2024-07-01T23:59:59Z"

Example Response:

[
  {
    "id": "123456",
    "latitude": "40.7128",
    "longitude": "-74.0060",
    "elevation": "10.5",
    "time": "2024-07-10T12:34:56Z",
    "metadata": {
      "description": "New York City",
      "accuracy": 10,
      "activity": "walking"
    },
    "createdAt": "2024-07-10T12:34:56Z",
    "updatedAt": "2024-07-10T12:34:56Z",
    "userId": "user123"
  }
]

Geographical Bounding Box Filter

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer TOKEN" \
     "https://api.magicrail.io/locations?north=40.9176&south=40.4774&east=-73.7004&west=-74.2591"

Example Response:

[
  {
    "id": "123456",
    "latitude": "40.7128",
    "longitude": "-74.0060",
    "elevation": "10.5",
    "time": "2024-07-10T12:34:56Z",
    "metadata": {
      "description": "New York City",
      "accuracy": 10,
      "activity": "walking"
    },
    "createdAt": "2024-07-10T12:34:56Z",
    "updatedAt": "2024-07-10T12:34:56Z",
    "userId": "user123"
  }
]

Proximity to a Point Filter

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer TOKEN" \
     "https://api.magicrail.io/locations?lat=40.7128&lon=-74.0060&radius=10km"

Example Response:

[
  {
    "id": "123456",
    "latitude": "40.7128",
    "longitude": "-74.0060",
    "elevation": "10.5",
    "time": "2024-07-10T12:34:56Z",
    "metadata": {
      "description": "New York City",
      "accuracy": 10,
      "activity": "walking"
    },
    "createdAt": "2024-07-10T12:34:56Z",
    "updatedAt": "2024-07-10T12:34:56Z",
    "userId": "user123"
  }
]

Elevation Range Filter

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer TOKEN" \
     "https://api.magicrail.io/locations?elevation_min=5&elevation_max=15"

Example Response:

[
  {
    "id": "123456",
    "latitude": "40.7128",
    "longitude": "-74.0060",
    "elevation": "10.5",
    "time": "2024-07-10T12:34:56Z",
    "metadata": {
      "description": "New York City",
      "accuracy": 10,
      "activity": "walking"
    },
    "createdAt": "2024-07-10T12:34:56Z",
    "updatedAt": "2024-07-10T12:34:56Z",
    "userId": "user123"
  }
]

Metadata Filter

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer TOKEN" \
     "https://api.magicrail.io/locations?metadata[description]=New%20York%20City"

Example Response:

[
  {
    "id": "123456",
    "latitude": "40.7128",
    "longitude": "-74.0060",
    "elevation": "10.5",
    "time": "2024-07-10T12:34:56Z",
    "metadata": {
      "description": "New York City",
      "accuracy": 10,
      "activity": "walking"
    },
    "createdAt": "2024-07-10T12:34:56Z",
    "updatedAt": "2024-07-10T12:34:56Z",
    "userId": "user123"
  }
]

Metadata Key Presence Filter

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer TOKEN" \
     "https://api.magicrail.io/locations?metadata_key=description"

Example Response:

[
  {
    "id": "123456",
    "latitude": "40.7128",
    "longitude": "-74.0060",
    "elevation": "10.5",
    "time": "2024-07-10T12:34:56Z",
    "metadata": {
      "description": "New York City",
      "accuracy": 10,
      "activity": "walking"
    },
    "createdAt": "2024-07-10T12:34:56Z",
    "updatedAt": "2024-07-10T12:34:56Z",
    "userId": "user123"
  }
]

Activity Filter

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer TOKEN" \
     "https://api.magicrail.io/locations?activity=walking"

Example Response:

[
  {
    "id": "123456",
    "latitude": "40.7128",
    "longitude": "-74.0060",
    "elevation": "10.5",
    "time": "2024-07-10T12:34:56Z",
    "metadata": {
      "description": "New York City",
      "accuracy": 10,
      "activity": "walking"
    },
    "createdAt": "2024-07-10T12:34:56Z",
    "updatedAt": "2024-07-10T12:34:56Z",
    "userId": "user123"
  }
]