Quick Start Guide

This guide walks you through making your first Cirrosense API request. You will have live weather data in your application within minutes.

Step 1: Get an API Key

All requests to the Cirrosense API requires an API key passed as the key query parameter. The first step is to create an account to receive your key. Free accounts include up to 50K requests per month. See the authentication guide for more details on managing and securing your key.

Keep your key private. Do not expose it in client-side code or public repositories.

Step 2: Select an Endpoint

Cirrosense provides the following endpoints:

/current: Returns current weather conditions for a given location
/forecast: Returns daily and/or hourly weather forecast for a given location
/geocode: Returns a list of locations matching the given place name

View the endpoint documentation for more information on each of the endpoints

Endpoint Request Examples

GET /current Show Optional
```
curl -G https://api.cirrosense.com/current \
  -d "key=YOUR_CIRROSENSE_API_KEY" \
  -d "lat=40.7128" \
  -d "lon=-74.006" \
  -d "place=New York, NY" \
  -d "units=metric"
```
GET /forecast Show Optional
```
curl -G https://api.cirrosense.com/forecast \
  -d "key=YOUR_CIRROSENSE_API_KEY" \
  -d "lat=40.7128" \
  -d "lon=-74.006" \
  -d "place=New York, NY" \
  -d "units=metric" \
  -d "days=3" \
  -d "hourly=24"
```
GET /geocode Show Optional
```
curl -G https://api.cirrosense.com/geocode \
  -d "key=YOUR_CIRROSENSE_API_KEY" \
  -d "place=New York" \
  -d "limit=5"
```

Step 3: Understand the Response

Cirrosense will always return responses in JSON format. An HTTP response code of 200 will be used for all successful requests. Failed requests will use one of the following HTTP codes:

HTTP Code	Description
400	Invalid user input. For example, missing a required query parameter
401	Unauthorized. You either forgot to include the `key` parameter, or it was invalid
404	Not found. Check the endpoint you are trying to access and make sure it matches one of the endpoints listed in our documentation
429	Rate limit exceeded. This will happen when you make requests faster than is allowed for your subscription level. You will either need to reduce the rate you are calling the API, or upgrade your subscription

Successful Response Example

Here is an example of a successful response (from the geocoding endpoint):

{
  "results": [
    {
      "lat": 40.7128,
      "lon": -74.006,
      "name": "New York",
      "admin": "New York",
      "country": "United States",
      "iso2": "US",
      "timezone": "America/New_York"
    },
    ...
  ]
}

Error Response Example

All error responses will be in this format:

{
  "code": 401,
  "type": "invalid_key",
  "description": "The provided API key is not valid. Generate a new one in the portal",
  "docs": "https://cirrosense.com/docs/api-key"
}