Tomorrow.io LLM-Friendly Weather API Documentation

The Locations API allows you to manage predefined locations that can be queried in any of the weather data endpoints. Locations are primarily used by Monitors and can be linked to Alerts for constant monitoring of weather conditions.

Key Features: Support for Point, Polygon, and Polyline geometries • Location tagging and organization • Integration with monitoring and alerting systems

Information

Important: Deleting a location unlinks it from alerts and dashboards, and it will no longer be monitored. Use location tags to organize and manage your locations effectively.

Supported Geometry Types

Point Geometry

A point location is defined by a geometry object according to the GeoJSON format, where the type is "Point" and coordinates are a single pair of longitude, latitude coordinates.

Point ExampleJSON
{
  "type": "Point",
  "coordinates": [125.6, 10.1]
}

Polygon Geometry

A polygon location is defined by a geometry object according to the GeoJSON format, where the type is "Polygon" and coordinates are an array of longitude pair coordinates. All polygons must be 500 sq km or smaller.

Polygon ExampleJSON
{
  "type": "Polygon",
  "coordinates": [[
    [100.0, 0.0],
    [101.0, 0.0],
    [101.0, 1.0],
    [100.0, 1.0],
    [100.0, 0.0]
  ]]
}

Polyline Geometry

A polyline location is defined by a geometry object according to the GeoJSON format, where the type is "LineString" and coordinates are an array of longitude pair coordinates. All polylines must be 70 km or shorter.

Polyline ExampleJSON
{
  "type": "LineString",
  "coordinates": [[-100, 40], [-105, 45], [-110, 55]]
}

List Locations

https://api.tomorrow.io/v4/locations

Request Parameters

Parameter	Type	Required	Description	Example
`apikey`	String	Required	Your Tomorrow.io API key for authentication	`YOUR_API_KEY`

Request Example

cURL RequestBASH
curl --request GET \
  --url 'https://api.tomorrow.io/v4/locations?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate'

Response Example

200 Success ResponseJSON
{
  "data": {
    "locations": [
      {
        "id": "5b080f93b801a20006aad803",
        "name": "Nationals Park",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -77.00698228888548,
            38.87304361125584
          ]
        },
        "timezone": "America/New_York",
        "tags": [
          "israel",
          "Stadiums",
          "logistics Employee Health & Safety 2024-08-08 16:0"
        ],
        "createdAt": "2019-03-03T11:01:43.327Z",
        "updatedAt": "2025-06-10T08:50:33.380Z",
        "isAccountResource": true,
        "direction": null
      },
      {
        "id": "5b080f93b801a20006aad811",
        "name": "Missouri Test",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -92.04785169661044,
            39.09425748182842
          ]
        },
        "timezone": "America/Chicago",
        "tags": [
          "junk",
          "japan",
          "Stadiums"
        ],
        "createdAt": "2019-03-03T11:01:43.327Z",
        "updatedAt": "2025-06-10T08:50:33.380Z",
        "isAccountResource": true
      }
    ]
  },
  "meta": {
    "totalItems": 1440
  },
  "links": {
    "self": "/v4/locations?limit=10&offset=0",
    "next": "/v4/locations?limit=10&offset=10"
  }
}

Create a Location

Create Location

https://api.tomorrow.io/v4/locations

Request Parameters

Parameter	Type	Required	Description	Example
`name`	String	Required	The name of the location	`Downtown Office`
`geometry`	GeoJSON Object	Required	The GeoJSON geometry representation of the location object (Point, Polygon, or LineString)	`{"type": "Point", "coordinates": [125.6, 10.1]}`
`tags`	Array<String>	Optional	Array of tags to categorize and organize the location	`["office", "priority"]`
`direction`	Number	Optional	The location direction in degrees clockwise from due north (0-360)	`45.5`

Request Example

cURL RequestBASH
curl --request POST \
  --url 'https://api.tomorrow.io/v4/locations?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Downtown Office",
    "geometry": {
      "type": "Point",
      "coordinates": [125.6, 10.1]
    },
    "tags": ["office", "priority"],
    "direction": 45.5
  }'

Response Example

200 Success ResponseJSON
{
  "data": {
    "location": {
      "id": "685969b020550914a1fb5300",
      "name": "Test Location LLM Docs",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -74.006,
          40.7128
        ]
      },
      "timezone": "America/New_York",
      "tags": [
        "test",
        "documentation"
      ],
      "createdAt": "2025-06-23T14:50:24.704Z",
      "updatedAt": "2025-06-23T14:50:24.704Z",
      "isAccountResource": true
    }
  }
}

Retrieve a Location

Retrieve Location

https://api.tomorrow.io/v4/locations/{locationId}

Request Parameters

Parameter	Type	Required	Description	Example
`locationId`	String	Required	ID of a pre-defined location	`location_id_123`
`apikey`	String	Required	Your Tomorrow.io API key for authentication	`YOUR_API_KEY`

Request Example

cURL RequestBASH
curl --request GET \
  --url 'https://api.tomorrow.io/v4/locations/location_id_123?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate'

Response Example

200 Success ResponseJSON
{
  "data": {
    "location": {
      "id": "location_id_123",
      "name": "Downtown Office",
      "geometry": {
        "type": "Point",
        "coordinates": [125.6, 10.1]
      },
      "tags": ["office", "priority"],
      "direction": 45.5,
      "created": "2023-01-01T00:00:00Z",
      "updated": "2023-01-01T00:00:00Z"
    }
  }
}

Update a Location

Update Location

https://api.tomorrow.io/v4/locations/{locationId}

Request Parameters

Parameter	Type	Required	Description	Example
`locationId`	String	Required	ID of a pre-defined location	`location_id_123`
`name`	String	Optional	Updated name of the location	`Updated Office Name`
`geometry`	GeoJSON Object	Optional	Updated GeoJSON geometry representation of the location	`{"type": "Point", "coordinates": [126.0, 10.5]}`
`tags`	Array<String>	Optional	Updated array of tags for the location	`["office", "updated"]`
`direction`	Number	Optional	Updated location direction in degrees	`90.0`

Request Example

cURL RequestBASH
curl --request PUT \
  --url 'https://api.tomorrow.io/v4/locations/location_id_123?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Office Name",
    "direction": 90.0
  }'

Response Example

200 Success ResponseJSON
{
  "data": {
    "location": {
      "id": "location_id_123",
      "name": "Updated Office Name",
      "geometry": {
        "type": "Point",
        "coordinates": [125.6, 10.1]
      },
      "tags": ["office", "priority"],
      "direction": 90.0,
      "created": "2023-01-01T00:00:00Z",
      "updated": "2023-01-01T12:00:00Z"
    }
  }
}

Delete a Location

Delete Location

https://api.tomorrow.io/v4/locations/{locationId}

Request Parameters

Parameter	Type	Required	Description	Example
`locationId`	String	Required	ID of a pre-defined location	`location_id_123`
`apikey`	String	Required	Your Tomorrow.io API key for authentication	`YOUR_API_KEY`

Request Example

cURL RequestBASH
curl --request DELETE \
  --url 'https://api.tomorrow.io/v4/locations/location_id_123?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate'

Response Example

204 Success ResponseJSON
{
  "message": "Location deleted successfully"
}

Add Location Tags

https://api.tomorrow.io/v4/locations/tags/add

Request Parameters

Parameter	Type	Required	Description	Example
`locations`	Array<String>	Required	List of location IDs to add tags to	`["location_id_1", "location_id_2"]`
`tags`	Array<String>	Required	List of tags to be added to locations	`["urgent", "monitoring"]`

Request Example

cURL Request

curl --request POST \
  --url 'https://api.tomorrow.io/v4/locations/tags/add?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "locations": ["location_id_1", "location_id_2"],
    "tags": ["urgent", "monitoring"]
  }'

Response Example

204 Success Response

{
  "message": "Tags added successfully"
}

Remove Location Tags

https://api.tomorrow.io/v4/locations/tags/remove

Request Parameters

Parameter	Type	Required	Description	Example
`locations`	Array<String>	Required	List of location IDs to remove tags from	`["location_id_1", "location_id_2"]`
`tags`	Array<String>	Required	List of tags to be removed from locations	`["urgent", "monitoring"]`

Request Example

cURL Request

curl --request POST \
  --url 'https://api.tomorrow.io/v4/locations/tags/remove?apikey=YOUR_API_KEY' \
  --header 'Accept-Encoding: gzip, deflate' \
  --header 'Content-Type: application/json' \
  --data '{
    "locations": ["location_id_1", "location_id_2"],
    "tags": ["urgent", "monitoring"]
  }'

Response Example

204 Success Response

{
  "message": "Tags removed successfully"
}

Error Responses

400 Bad Request

Invalid Request Format

{
  "code": 400,
  "type": "Bad Request",
  "message": "Invalid request format or missing required parameters"
}

401 Unauthorized

Invalid API Key

{
  "code": 401,
  "type": "Unauthorized",
  "message": "Invalid API key or insufficient permissions"
}

404 Not Found

Location Not Found

{
  "code": 404,
  "type": "Not Found",
  "message": "Location not found"
}