--- updatedAt: 2025-06-04T20:41:24.000Z agentTools: projectIndex: https://docs.tomorrow.io/llms.txt --- # Build Your Own Weather App With One Call ```node Node const fetch = require("node-fetch"); const queryString = require('query-string'); const moment = require("moment"); // set the Timelines GET endpoint as the target URL const getTimelineURL = "https://api.tomorrow.io/v4/timelines"; // get your key from app.tomorrow.io/development/keys const apikey = "add your API key here"; // pick the location, as a latlong pair let location = [40.758, -73.9855]; // list the fields const fields = [ "precipitationIntensity", "precipitationType", "windSpeed", "windGust", "windDirection", "temperature", "temperatureApparent", "cloudCover", "cloudBase", "cloudCeiling", "weatherCode", ]; // choose the unit system, either metric or imperial const units = "imperial"; // set the timesteps, like "current", "1h" and "1d" const timesteps = ["current", "1h", "1d"]; // configure the time frame up to 6 hours back and 15 days out const now = moment.utc(); const startTime = moment.utc(now).add(0, "minutes").toISOString(); const endTime = moment.utc(now).add(1, "days").toISOString(); // specify the timezone, using standard IANA timezone format const timezone = "America/New_York"; // request the timelines with all the query string parameters as options const getTimelineParameters = queryString.stringify({ apikey, location, fields, units, timesteps, startTime, endTime, timezone, }, {arrayFormat: "comma"}); fetch(getTimelineURL + "?" + getTimelineParameters, {method: "GET", compress: true}) .then((result) => result.json()) .then((json) => console.log(json) .catch((error) => console.error("error: " + err)); /* ---- [PREMIUM FEATURE] contact sales@tomorrow.io ---- // set the Timelines POST endpoint as the target URL const postTimelineURL = 'https://api.tomorrow.io/v4/timelines' + "?apikey=" + apikey; fields = { "precipitationIntensityMax", "precipitationTypeMax", "windSpeedAverage", "temperatureMin", "temperatureMax", "cloudCoverMax" } location = { "type":"Polygon", "coordinates": [[[-73.985043,40.753554],[-73.990724,40.75595],[-73.984726,40.764167],[-73.979057,40.761747],[-73.985043,40.753554]]] } const postTimelineOptions = {method: 'POST', compress: true, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ location fields, units, timesteps, startTime, endTime, timezone })}; fetch(postTimelineURL, postTimelineOptions) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error('error: ' + err)); */ ``` ```json Response Example { "data": { "timelines": [ { "timestep": "current", "startTime": "2021-03-24T14:47:00-04:00", "endTime": "2021-03-24T14:47:00-04:00", "intervals": [ { "startTime": "2021-03-24T14:47:00-04:00", "values": { "precipitationIntensity": 0.0083, "precipitationType": 1, "windSpeed": 3, "windGust": 6.98, "windDirection": 21, "temperature": 56.98, "temperatureApparent": 55.87, "cloudCover": 100, "cloudBase": null, "cloudCeiling": null, "weatherCode": 4000 } } ] }, { "timestep": "1h", "startTime": "2021-03-24T14:47:00-04:00", "endTime": "2021-03-25T14:47:00-04:00", "intervals": [ { "startTime": "2021-03-24T14:47:00-04:00", "values": { "precipitationIntensity": 0.0083, "precipitationType": 1, "windSpeed": 3, "windGust": 6.98, "windDirection": 21, "temperature": 56.98, "temperatureApparent": 55.87, "cloudCover": 100, "cloudBase": null, "cloudCeiling": null, "weatherCode": 4000 } }, { "startTime": "2021-03-24T15:47:00-04:00", "values": { "precipitationIntensity": 0.0161, "precipitationType": 1, "windSpeed": 9.78, "windGust": 19.35, "windDirection": 140.41, "temperature": 57.92, "temperatureApparent": 57.97, "cloudCover": 100, "cloudBase": 0.71, "cloudCeiling": 3.44, "weatherCode": 4000 } }, { "startTime": "2021-03-24T16:47:00-04:00", "values": { "precipitationIntensity": 0.1362, "precipitationType": 1, "windSpeed": 10.11, "windGust": 23.04, "windDirection": 120.83, "temperature": 55.29, "temperatureApparent": 55.29, "cloudCover": 100, "cloudBase": 0.45, "cloudCeiling": 0.27, "weatherCode": 4001 } }, { "startTime": "2021-03-24T17:47:00-04:00", "values": { "precipitationIntensity": 0.2555, "precipitationType": 1, "windSpeed": 12.17, "windGust": 27.58, "windDirection": 112.24, "temperature": 53.53, "temperatureApparent": 53.53, "cloudCover": 100, "cloudBase": 0.11, "cloudCeiling": 0.19, "weatherCode": 4001 } }, { "startTime": "2021-03-24T18:47:00-04:00", "values": { "precipitationIntensity": 0.1323, "precipitationType": 1, "windSpeed": 9.64, "windGust": 21.41, "windDirection": 110.08, "temperature": 53.06, "temperatureApparent": 53.06, "cloudCover": 100, "cloudBase": 0.09, "cloudCeiling": 0.12, "weatherCode": 4001 } }, { "startTime": "2021-03-24T19:47:00-04:00", "values": { "precipitationIntensity": 0.089, "precipitationType": 1, "windSpeed": 9.71, "windGust": 23.96, "windDirection": 115.64, "temperature": 53.06, "temperatureApparent": 53.06, "cloudCover": 100, "cloudBase": 0.09, "cloudCeiling": 0.14, "weatherCode": 4200 } }, { "startTime": "2021-03-24T20:47:00-04:00", "values": { "precipitationIntensity": 0.0728, "precipitationType": 1, "windSpeed": 10.47, "windGust": 24.67, "windDirection": 115.09, "temperature": 53.1, "temperatureApparent": 53.1, "cloudCover": 100, "cloudBase": 0.12, "cloudCeiling": 0.19, "weatherCode": 4200 } }, { "startTime": "2021-03-24T21:47:00-04:00", "values": { "precipitationIntensity": 0.0457, "precipitationType": 1, "windSpeed": 9.1, "windGust": 23.15, "windDirection": 124.12, "temperature": 52.74, "temperatureApparent": 52.74, "cloudCover": 100, "cloudBase": 0.12, "cloudCeiling": 0.12, "weatherCode": 4200 } }, { "startTime": "2021-03-24T22:47:00-04:00", "values": { "precipitationIntensity": 0.115, "precipitationType": 1, "windSpeed": 5.5, "windGust": 13.62, "windDirection": 103.64, "temperature": 52.09, "temperatureApparent": 52.09, "cloudCover": 100, "cloudBase": 0.09, "cloudCeiling": 0.08, "weatherCode": 4001 } }, { "startTime": "2021-03-24T23:47:00-04:00", "values": { "precipitationIntensity": 0.05, "precipitationType": 1, "windSpeed": 4.65, "windGust": 8.75, "windDirection": 99.12, "temperature": 51.85, "temperatureApparent": 51.85, "cloudCover": 100, "cloudBase": 0.06, "cloudCeiling": 0.1, "weatherCode": 4200 } }, { "startTime": "2021-03-25T00:47:00-04:00", "values": { "precipitationIntensity": 0.0055, "precipitationType": 1, "windSpeed": 4.7, "windGust": 7.25, "windDirection": 70.27, "temperature": 51.48, "temperatureApparent": 51.48, "cloudCover": 100, "cloudBase": 0.03, "cloudCeiling": 0.03, "weatherCode": 4000 } }, { "startTime": "2021-03-25T01:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 4.9, "windGust": 6.89, "windDirection": 47.32, "temperature": 50.67, "temperatureApparent": 50.67, "cloudCover": 100, "cloudBase": 0.03, "cloudCeiling": 0.03, "weatherCode": 2000 } }, { "startTime": "2021-03-25T02:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 5.44, "windGust": 8.3, "windDirection": 34.38, "temperature": 49.68, "temperatureApparent": 49.68, "cloudCover": 100, "cloudBase": 0.03, "cloudCeiling": 0.03, "weatherCode": 2000 } }, { "startTime": "2021-03-25T03:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 6.42, "windGust": 10.67, "windDirection": 31.86, "temperature": 49.66, "temperatureApparent": 49.66, "cloudCover": 100, "cloudBase": 0.03, "cloudCeiling": 0.03, "weatherCode": 2000 } }, { "startTime": "2021-03-25T04:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 5.79, "windGust": 10.33, "windDirection": 39.19, "temperature": 50.05, "temperatureApparent": 50.05, "cloudCover": 100, "cloudBase": 0.03, "cloudCeiling": 0.03, "weatherCode": 2000 } }, { "startTime": "2021-03-25T05:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 5.37, "windGust": 10.38, "windDirection": 53.95, "temperature": 50.23, "temperatureApparent": 50.23, "cloudCover": 100, "cloudBase": 0.03, "cloudCeiling": 0.03, "weatherCode": 2000 } }, { "startTime": "2021-03-25T06:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 4.72, "windGust": 8.79, "windDirection": 15.24, "temperature": 49.5, "temperatureApparent": 49.5, "cloudCover": 100, "cloudBase": 0.03, "cloudCeiling": 0.03, "weatherCode": 2000 } }, { "startTime": "2021-03-25T07:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 3.74, "windGust": 8.21, "windDirection": 3.2, "temperature": 50.05, "temperatureApparent": 50.05, "cloudCover": 100, "cloudBase": 0.03, "cloudCeiling": 0.03, "weatherCode": 2000 } }, { "startTime": "2021-03-25T08:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 3.67, "windGust": 9.44, "windDirection": 303.72, "temperature": 53.47, "temperatureApparent": 53.47, "cloudCover": 27.78, "cloudBase": null, "cloudCeiling": null, "weatherCode": 1100 } }, { "startTime": "2021-03-25T09:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 3.2, "windGust": 9.95, "windDirection": 226.21, "temperature": 57.09, "temperatureApparent": 57.09, "cloudCover": 56.15, "cloudBase": 0.12, "cloudCeiling": 0.12, "weatherCode": 1101 } }, { "startTime": "2021-03-25T10:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 4.83, "windGust": 12.8, "windDirection": 219.44, "temperature": 60.13, "temperatureApparent": 60.13, "cloudCover": 63.41, "cloudBase": 0.19, "cloudCeiling": 0.26, "weatherCode": 1102 } }, { "startTime": "2021-03-25T11:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 4.61, "windGust": 12.68, "windDirection": 219.67, "temperature": 63.25, "temperatureApparent": 63.25, "cloudCover": 22.55, "cloudBase": null, "cloudCeiling": null, "weatherCode": 1100 } }, { "startTime": "2021-03-25T12:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 6.4, "windGust": 15.35, "windDirection": 205.34, "temperature": 65.93, "temperatureApparent": 65.93, "cloudCover": 3.15, "cloudBase": null, "cloudCeiling": null, "weatherCode": 1000 } }, { "startTime": "2021-03-25T13:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 8.32, "windGust": 18.03, "windDirection": 206.54, "temperature": 68.47, "temperatureApparent": 68.47, "cloudCover": 2.61, "cloudBase": null, "cloudCeiling": null, "weatherCode": 1000 } }, { "startTime": "2021-03-25T14:47:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 9.51, "windGust": 19.55, "windDirection": 194.03, "temperature": 70.03, "temperatureApparent": 70.03, "cloudCover": 61.87, "cloudBase": null, "cloudCeiling": null, "weatherCode": 1101 } } ] }, { "timestep": "1d", "startTime": "2021-03-24T06:00:00-04:00", "endTime": "2021-03-25T06:00:00-04:00", "intervals": [ { "startTime": "2021-03-24T06:00:00-04:00", "values": { "precipitationIntensity": 0.3762, "precipitationType": 1, "windSpeed": 12.86, "windGust": 28.79, "windDirection": 87.45, "temperature": 58.16, "temperatureApparent": 58.16, "cloudCover": 100, "cloudBase": 0.71, "cloudCeiling": 6.46, "weatherCode": 4200 } }, { "startTime": "2021-03-25T06:00:00-04:00", "values": { "precipitationIntensity": 0, "precipitationType": 1, "windSpeed": 9.74, "windGust": 19.83, "windDirection": 164.73, "temperature": 70.33, "temperatureApparent": 70.33, "cloudCover": 100, "cloudBase": 0.19, "cloudCeiling": 0.26, "weatherCode": 2000 } } ] } ] }, "warnings": [ { "code": 246009, "type": "Missing Time Range", "message": "The timestep is not supported in full for the time range requested.", "meta": { "timestep": "current", "from": "now", "to": "+1m" } } ] } ``` # Introduction to this guide **With our new Timelines endpoint, you can query any data points to your locations with just a single call.** In this guide, we'll walk you through making a query for a Point location defined by a simple latlong pair of one of our favorite places, Times Square in NY, using the GET call. However, with premium features, you can also query minimum/maximum/average values of data points throughout a Polygon or Polyline with the POST call. We added a commented-out example of this towards the end of the code. # Get your key Before we begin, make sure to [signup to our platform](https://www.tomorrow.io/weather-api/) and, once logged in, [grab your key](https://app.tomorrow.io/development/keys). # Pick the location In this type of call, only two [types of location](https://docs.tomorrow.io/reference/api-formats#locations) values are supported - either a `latlong` pair (separate by a comma) or a `locationId` of a predefined location in the system (see the [/locations endpoints](https://docs.tomorrow.io/reference/locations-overview)) In your app, you can change these per query dynamically, though we chose to only get the weather data for Times Square in New York City. Scroll all the way to the end of the code to see how you can query Polygons and Polylines, as part of our premium feature set. # List the fields All accounts come with the [Core data layer](https://docs.tomorrow.io/reference/data-layers-core) for free and with samples of the premium data layers such as [air quality](https://docs.tomorrow.io/reference/data-layers-air) and [pollen](https://docs.tomorrow.io/reference/data-layers-pollen). The app we're building requires only the basics, such as `precipitation`, `wind`, `temperature`, `clouds`, and `weather code`. But, if you're interested in getting full access to premium data points like [solar irradiance](https://docs.tomorrow.io/reference/solar), [soil moisture](https://docs.tomorrow.io/reference/solar), or [wave height](https://docs.tomorrow.io/reference/maritime), make sure to reach out to [sales@tomorrow.io](mailto:sales@tomorrow.io) Note that [some field values might be null](https://docs.tomorrow.io/reference/api-formats#nulls), when there isn't a valid numerical value - like wind direction when there's no wind. # Choose the unit system You can select either the imperial or metric unit system. This applies to all of the fields in the query. Now, in the US the common system is imperial consisting of units such as the inch, the mile, and the pound - so that's our choice. The Timeline response payload is lean, flat, and language-agnostic by-design, containing only the raw field values as numbers, enums, or [ISO-8601 timestamps](https://docs.tomorrow.io/reference/api-formats#date-and-time). This allows our developers to use it on mobile devices and translate the [field units' representative strings](https://docs.tomorrow.io/reference/weather-data-layers#field-descriptors) to the language of their choice. # Set the timesteps As mentioned, the Timelines endpoint allows you to request multiple timesteps with one call. Any of the following values are supported to choose the interval for which the data is provided: `1m`, `5m`, `15m`, `30m`, `1h`, `1d`, and current (which provides realtime measurements). For each field, you will find the [applicable timestep](https://docs.tomorrow.io/reference/weather-data-layers#timestep-availability) for its time frame, whereas In any case of two different timesteps - like “m” (minutes), “h” (hours) or “d” (days) - the data is available for any timesteps options between them. Given that we asked for the `1d` timesteps, it's important to highlight that whenever a [Min/Max/Avg suffix](https://docs.tomorrow.io/reference/weather-data-layers#field-availability) is not added to the named field, the API will resolve the max value. You can always get super-specific by adding Min/Max/Avg to get the values you want. Moreover, you can add MinTime and MaxTime if you want to know when at the earliest these values will be met in the day interval. # Configure the time frame In this example, we're only interested in getting the upcoming day, though most of our data points are support up to 6 hours back and 15 days out. Check out the [Frame annotation](https://docs.tomorrow.io/reference/weather-data-layers#field-availability) of each data point to learn more about its availability. Notice that we used `utc` as the input timezone, but your can use whichever zone you want. # Specify the timezone Regardless of the input timezone, mentioned in the `startTime` and `endTime` timestamps, you can request the returned timestamps to be in a different zone. Just make sure to use the [standard IANA Time Zone Database format](https://docs.tomorrow.io/reference/api-formats#timezone). Since we're going to get the data for Times Square, we will want it in New York's timezone. # Request the timelines Last, but not least, you can compile all of the query string parameters as part of the options. Use the `result` JSON response to parse the intervals of the timelines - each for a single timestep, as defined in the request. Check out the result example to see what you would get if you simply copy-paste this script into your code. Don't forget to "enrich" the fields with their [corresponding units](https://docs.tomorrow.io/reference/data-layers-overview#field-descriptors), according to the system selected. And we also have a (free SVG-based icon library)[ref:data-layers-core#data-layers-weather-codes] you can use to map the `weatherCode` values. # [PREMIUM FEATURE] Polygon/Polyline Locations Now, in case you have access to [Polygon/Polyline-type locations](https://docs.tomorrow.io/reference/locations-overview), you can query the POST Timeline endpoint with a (GeoJSON)[http://geojson.io/] `geometry` structure. Remember, our weather data is hyperlocal - up to the 500 meters. Though, if we want to query the entire Theatre District home of the Times Square, we can set the location as a Polygon. Notice that in our field naming we specified whether we want the min/max/average throughout the coverage area by adding the respective suffix. You can even get the weather along the Hudson river by querying a LineString, aka Polyline. Reach out to our awesome sales team at sales@tomorrow.io to learn more about this and other premium features.