Documentação

Página principal →

# Sobre o projeto

Api Catanuvem é um projeto pessoal criado a partir de um projeto hobbie que necessitava de dados sobre a condição climática. Apesar de já existir soluções de api's gratuitas para usar, decidi criar uma solução própria com os requisitos ideais para meu projeto. Na qual compreendi melhor os processos e foi de grande aprendizado.

# Features

  • Response em formato JSON
  • Busca por coordenadas ou nome da cidade
  • Previsão do clima hoje
  • Previsão do clima próximas 5 horas
  • Previsão do clima próximos 5 dias

# Como utilizar a api

A api de previsão climática é capaz de realizar consulta dos dados por coordenadas ou pelo nome da cidade e do estado.

O path principal e utilizado em todas as consultas é /weather, em seguida o período de busca e depois o método.

Exemplo: https://api-catanuvem.vercel.app/weather/:period/:method/...

:period = período da busca

:method = método da busca

Períodos de busca

São 3 períodos de busca aceitos pela api Catanuvem:

  • /today: retorna dados do clima de hoje

    Exemplo: https://api-catanuvem.vercel.app/weather/today/...

  • /hours: retorna dados do clima das próximas 5 horas

    Exemplo: https://api-catanuvem.vercel.app/weather/hours/...

  • /days: retorna dados do clima dos próximos 5 dias

    Exemplo: https://api-catanuvem.vercel.app/weather/days/...

Métodos de busca

São 2 métodos de busca aceitos pela api Catanuvem:

  • /loc: a consulta é realizada a partir das coordenadas informadas

    Exemplo: https://api-catanuvem.vercel.app/weather/today/loc/:lat&:lon

    :lat = latitude (Ex.: -15.7801)

    & = separador entre os valores

    :lon = longitude (Ex.: -47.9292)

  • /city: a consulta é realizada a partir do nome da cidade informada

    Exemplo: https://api-catanuvem.vercel.app/weather/today/city/:name/:state

    :name = nome da cidade (Ex.: Brasília)

    :state = sigla do estado (Ex.: DF)

# Exemplos de uso

Caso 1:

Buscando clima de hoje pelas coordenadas do local:

Exemplo: https://api-catanuvem.vercel.app/weather/today/loc/-15.7801&-47.9292

Caso 2:

Buscando clima de hoje pelo nome da cidade:

Exemplo: https://api-catanuvem.vercel.app/weather/today/city/Brasília/DF


Retorno da requisição em formato JSON:

                        
// 20221029172109
// https://api-catanuvem.vercel.app/weather/today/loc/-15.7801&-47.9292

{
    "location": "Brasília, Distrito Federal",
    "temperature": "23°",
    "condition": "Encoberto",
    "dayAndNight": "Dia 28° • Noite 19°",
    "icon": {
        "name": "Mostly Cloudy",
        "src": "https://api-catanuvem.vercel.app/icons/Mostly%20Cloudy.svg"
    },
    "precipitation": "68%",
    "feelsLike": "23°",
    "wind": "16 km/h",
    "humidity": "72%",
    "dewPoint": "17°",
    "pressure": "1015.2 mb",
    "uvIndex": "0 de 10",
    "visibility": "9.66 km",
    "moon": "Lua crescente",
    "climateVariation": {
        "max": "--",
        "min": "19°"
    },
    "airQuality": {
        "score": "44",
        "quality": "Boa",
        "description": "A qualidade do ar é considerada satisfatória, e a poluição do ar representa risco pequeno ou nulo."
    },
    "sun": {
        "sunrise": "5:36",
        "sunset": "18:14"
    },
    "todayForecast": [
        {
        "period": "Manhã",
        "temperature": "26°",
        "icon": {
            "name": "Partly Cloudy",
            "src": "https://api-catanuvem.vercel.app/icons/Partly%20Cloudy.svg"
        },
        "precipitation": "--"
        },
        {
        "period": "Tarde",
        "temperature": "24°",
        "icon": {
            "name": "Mostly Cloudy",
            "src": "https://api-catanuvem.vercel.app/icons/Mostly%20Cloudy.svg"
        },
        "precipitation": "--"
        },
        {
        "period": "Noite",
        "temperature": "21°",
        "icon": {
            "name": "Thunderstorm",
            "src": "https://api-catanuvem.vercel.app/icons/Thunderstorm.svg"
        },
        "precipitation": "71%"
        },
        {
        "period": "A noite",
        "temperature": "20°",
        "icon": {
            "name": "Cloudy",
            "src": "https://api-catanuvem.vercel.app/icons/Mostly%20Cloudy.svg"
        },
        "precipitation": "24%"
        }
    ]
}

# Dicionário: keys do Response

  • location: retorna a localização
  • temperature: temperatura do clima no momento da requisição
  • condition: condição do clima no momento da requisição
  • dayAndNight: temperatura esperada para o dia e a noite
  • icon: ícone condição do clima atual, possui dois atributos
    • name: nome do ícone
    • src: caminho src do ícone
  • precipitation: precipitação, é probabilidade de chuva, granizo...
  • feelsLike: sensação térmica do clima no momento da requisição
  • wind: velocidade em km/h do vento
  • humidity: umidade do ar
  • dewPoint: ponto de orvalho
  • pressure: pressão atmosférica
  • uvIndex: índice de ráios UV
  • visibility: visibilidade do local da requisição
  • moon: fase da lua no momento da requisição
  • climateVariation: máxima e mínima temperatura do dia
    • max: máxima temperatura
    • min: mínima temperatura
  • airQuality: qualidade do ar no local da requisição
    • score: pontuação da qualidade do ar
    • quality: título sobre a qualidade do ar
    • description: descrição sobre a qualidade do ar
  • sun: horário do nascer e pôr do sol
    • sunrise: horário do nascer do sol
    • sunset: horário do pôr do sol
  • todayForecast: previsão do clima para hoje
    • period: período do dia (manhã, tarde, noite...)
    • temperature: temperatura do período
    • icon: ícone condição do clima do período (atributos: name, src)
    • precipitation: precipitação do tempo no período
  • hoursForecast: previsão do clima para as próximas 5 horas
    • hour: hora da previsão do clima
    • temperature: temperatura do clima
    • icon: ícone condição do clima do período (atributos: name, src)
    • precipitation: precipitação do tempo no período
  • forecastNextDays: previsão do clima para os próximos 5 dias
    • day: dia da previsão do clima
    • max: temperatura máxima do dia
    • min: temperatura mínima do dia
    • icon: ícone condição do clima do período (atributos: name, src)
    • precipitation: precipitação do tempo no período