{ "openapi": "3.1.0", "info": { "title": "Tempo Pelotas API PRO", "version": "1.0.0", "summary": "API versionada de meteorologia, alertas, status e hidrologia do Tempo Pelotas.", "description": "Contrato OpenAPI da superfície V1 atualmente publicada em produção.\n\nCompatibilidade: dentro da V1, campos podem ser adicionados de forma compatível, mas campos documentados não devem mudar de significado ou tipo sem uma nova versão major da API.\nObservação, previsão, alerta e hidrologia permanecem classes distintas. Hidrologia só é anunciada para cidades com contrato explícito de estação/série.\nNenhum exemplo contém API key, token, cookie, segredo de provider ou header autenticado real.", "contact": { "name": "Tempo Pelotas", "url": "https://tempopelotas.com.br/" } }, "servers": [ { "url": "https://tempopelotas.com.br/api/v1", "description": "Produção" } ], "tags": [ { "name": "Cities", "description": "Descoberta de cidades e módulos disponíveis." }, { "name": "Weather", "description": "Previsão meteorológica municipal." }, { "name": "Alerts", "description": "Avisos oficiais do INMET por município." }, { "name": "Status", "description": "Estado da integração separado da condição publicável do dado." }, { "name": "Hydrology", "description": "Medições hidrológicas somente para contratos municipais explícitos." } ], "x-api-version": "v1", "x-compatibility-policy": { "additiveChanges": "allowed", "breakingChanges": "new major API version", "unknownFields": "clients should ignore unknown response fields" }, "paths": { "/cities": { "get": { "tags": [ "Cities" ], "operationId": "listCities", "summary": "Lista cidades públicas e os módulos implementados", "security": [ { "bearerAuth": [] } ], "x-required-scope": "cities:read", "responses": { "200": { "description": "Inventário público de cidades da API.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CitiesResponse" } } } }, "401": { "description": "API key ausente, malformada, expirada, revogada ou inválida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidApiKey": { "value": { "error": "invalid_api_key", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "403": { "description": "A credencial é válida, mas o cliente ou o escopo não autoriza a operação.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "insufficientScope": { "value": { "error": "insufficient_scope", "requiredScope": "cities:read", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "clientInactive": { "value": { "error": "client_inactive", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "proRequired": { "value": { "error": "pro_required", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "429": { "description": "Quota de minuto, dia ou mês excedida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "rateLimit": { "value": { "error": "rate_limit_exceeded", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "503": { "description": "A API ou uma dependência necessária para a operação está indisponível.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unavailable": { "value": { "error": "api_unavailable", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } } } } }, "/cities/{citySlug}/weather": { "get": { "tags": [ "Weather" ], "operationId": "getCityWeather", "summary": "Obtém a previsão meteorológica municipal", "security": [ { "bearerAuth": [] } ], "x-required-scope": "weather:read", "parameters": [ { "$ref": "#/components/parameters/CitySlug" } ], "responses": { "200": { "description": "Previsão meteorológica municipal.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WeatherResponse" } } } }, "401": { "description": "API key ausente, malformada, expirada, revogada ou inválida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidApiKey": { "value": { "error": "invalid_api_key", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "403": { "description": "A credencial é válida, mas o cliente ou o escopo não autoriza a operação.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "insufficientScope": { "value": { "error": "insufficient_scope", "requiredScope": "weather:read", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "clientInactive": { "value": { "error": "client_inactive", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "proRequired": { "value": { "error": "pro_required", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "404": { "description": "Cidade não encontrada no inventário público.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "cityNotFound": { "value": { "apiVersion": "v1", "error": "city_not_found", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "429": { "description": "Quota de minuto, dia ou mês excedida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "rateLimit": { "value": { "error": "rate_limit_exceeded", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "503": { "description": "API ou previsão municipal temporariamente indisponível.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "weatherUnavailable": { "value": { "apiVersion": "v1", "error": "weather_unavailable", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "apiUnavailable": { "value": { "error": "api_unavailable", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } } } } }, "/cities/{citySlug}/alerts": { "get": { "tags": [ "Alerts" ], "operationId": "getCityAlerts", "summary": "Obtém avisos oficiais do INMET para o município", "security": [ { "bearerAuth": [] } ], "x-required-scope": "alerts:read", "parameters": [ { "$ref": "#/components/parameters/CitySlug" } ], "responses": { "200": { "description": "Estado da consulta de alertas e itens ativos retornados.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertsResponse" } } } }, "401": { "description": "API key ausente, malformada, expirada, revogada ou inválida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidApiKey": { "value": { "error": "invalid_api_key", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "403": { "description": "A credencial é válida, mas o cliente ou o escopo não autoriza a operação.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "insufficientScope": { "value": { "error": "insufficient_scope", "requiredScope": "alerts:read", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "clientInactive": { "value": { "error": "client_inactive", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "proRequired": { "value": { "error": "pro_required", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "404": { "description": "Cidade não encontrada no inventário público.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Quota de minuto, dia ou mês excedida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "rateLimit": { "value": { "error": "rate_limit_exceeded", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "503": { "description": "API ou consulta municipal de alertas indisponível.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "alertsUnavailable": { "value": { "apiVersion": "v1", "error": "alerts_unavailable", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } } } } }, "/cities/{citySlug}/status": { "get": { "tags": [ "Status" ], "operationId": "getCityStatus", "summary": "Obtém o status das integrações e da condição publicável do dado", "security": [ { "bearerAuth": [] } ], "x-required-scope": "status:read", "parameters": [ { "$ref": "#/components/parameters/CitySlug" } ], "responses": { "200": { "description": "Status agregado das integrações weather e alerts.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } }, "401": { "description": "API key ausente, malformada, expirada, revogada ou inválida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidApiKey": { "value": { "error": "invalid_api_key", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "403": { "description": "A credencial é válida, mas o cliente ou o escopo não autoriza a operação.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "insufficientScope": { "value": { "error": "insufficient_scope", "requiredScope": "status:read", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "clientInactive": { "value": { "error": "client_inactive", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "proRequired": { "value": { "error": "pro_required", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "404": { "description": "Cidade não encontrada no inventário público.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Quota de minuto, dia ou mês excedida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "rateLimit": { "value": { "error": "rate_limit_exceeded", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "503": { "description": "API ou coleta de status municipal indisponível.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "statusUnavailable": { "value": { "apiVersion": "v1", "error": "status_unavailable", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } } } } }, "/cities/{citySlug}/hydrology": { "get": { "tags": [ "Hydrology" ], "operationId": "getCityHydrology", "summary": "Obtém medição hidrológica para cidades com contrato explícito", "description": "Não associa estação por proximidade. Séries de referências verticais distintas não são declaradas comparáveis.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "hydrology:read", "parameters": [ { "$ref": "#/components/parameters/CitySlug" } ], "responses": { "200": { "description": "Medição hidrológica e metadados de referência da série selecionada.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HydrologyResponse" } } } }, "401": { "description": "API key ausente, malformada, expirada, revogada ou inválida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "invalidApiKey": { "value": { "error": "invalid_api_key", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "403": { "description": "A credencial é válida, mas o cliente ou o escopo não autoriza a operação.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "insufficientScope": { "value": { "error": "insufficient_scope", "requiredScope": "hydrology:read", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "clientInactive": { "value": { "error": "client_inactive", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } }, "proRequired": { "value": { "error": "pro_required", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "404": { "description": "Cidade inexistente ou cidade sem contrato hidrológico implementado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "notSupported": { "value": { "apiVersion": "v1", "error": "hydrology_not_supported", "city": { "id": "4309654", "slug": "hulha-negra-rs", "name": "Hulha Negra" }, "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "429": { "description": "Quota de minuto, dia ou mês excedida.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "rateLimit": { "value": { "error": "rate_limit_exceeded", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } }, "503": { "description": "API ou coleta hidrológica municipal indisponível.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "X-API-Version": { "$ref": "#/components/headers/XApiVersion" }, "Link": { "$ref": "#/components/headers/OpenApiLink" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "hydrologyUnavailable": { "value": { "apiVersion": "v1", "error": "hydrology_unavailable", "requestId": "3ad0e978-33e4-4c06-bb99-45f024a9c7b2" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "tp_live__", "description": "API key Tempo Pelotas PRO. O plaintext é exibido somente no instante de emissão e não é persistido pelo servidor." } }, "parameters": { "CitySlug": { "name": "citySlug", "in": "path", "required": true, "description": "Slug municipal canônico do Tempo Pelotas, por exemplo `pelotas-rs`.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+-rs$" }, "example": "pelotas-rs" } }, "headers": { "XRequestId": { "description": "Identificador da requisição.", "schema": { "type": "string", "format": "uuid" } }, "XRateLimitLimit": { "description": "Limite da janela de quota atualmente relevante.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitRemaining": { "description": "Requisições restantes na janela atualmente relevante.", "schema": { "type": "integer", "minimum": 0 } }, "XRateLimitReset": { "description": "Epoch Unix em segundos para reset da janela atualmente relevante.", "schema": { "type": "integer", "minimum": 1 } }, "RetryAfter": { "description": "Segundos até a próxima tentativa permitida.", "schema": { "type": "integer", "minimum": 1 } }, "XApiVersion": { "description": "Versão major estável da Tempo Pelotas API que processou a resposta.", "schema": { "type": "string", "const": "v1" }, "example": "v1" }, "OpenApiLink": { "description": "Link de descoberta para o contrato OpenAPI 3.1 da API.", "schema": { "type": "string" }, "example": "; rel=\"service-desc\"" } }, "schemas": { "RequestId": { "type": "string", "format": "uuid" }, "ApiVersion": { "type": "string", "const": "v1" }, "CityIdentity": { "type": "object", "required": [ "id", "ibgeCode", "slug", "name", "state", "latitude", "longitude" ], "properties": { "id": { "type": "string", "pattern": "^\\d{7}$", "description": "Código IBGE." }, "ibgeCode": { "type": "string", "pattern": "^\\d{7}$" }, "slug": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string", "const": "RS" }, "latitude": { "type": "number" }, "longitude": { "type": "number" } } }, "CitySummary": { "allOf": [ { "$ref": "#/components/schemas/CityIdentity" }, { "type": "object", "required": [ "group", "portalPath", "modules" ], "properties": { "group": { "type": "string", "enum": [ "Pelotas e entorno", "Costa Doce", "Fronteira Sul", "Campanha" ] }, "portalPath": { "type": "string" }, "modules": { "type": "object", "required": [ "weather", "alerts", "status", "hydrology" ], "properties": { "weather": { "type": "boolean", "const": true }, "alerts": { "type": "boolean", "const": true }, "status": { "type": "boolean", "const": true }, "hydrology": { "type": "boolean" } } } } } ] }, "CitiesResponse": { "type": "object", "required": [ "apiVersion", "data", "generatedAt", "requestId" ], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CitySummary" } }, "generatedAt": { "type": "string", "format": "date-time" }, "requestId": { "$ref": "#/components/schemas/RequestId" } } }, "WeatherCurrentForecast": { "type": [ "object", "null" ], "required": [ "validAt", "temperature", "feelsLike", "condition", "humidity", "pressure", "precipitationMm", "windSpeed", "windGust", "windDirection" ], "properties": { "validAt": { "type": [ "string", "null" ] }, "temperature": { "type": [ "number", "null" ] }, "feelsLike": { "type": [ "number", "null" ] }, "condition": { "type": "string" }, "humidity": { "type": [ "number", "null" ] }, "pressure": { "type": [ "number", "null" ] }, "precipitationMm": { "type": [ "number", "null" ] }, "windSpeed": { "type": [ "number", "null" ] }, "windGust": { "type": [ "number", "null" ] }, "windDirection": { "type": [ "string", "null" ] } } }, "HourlyForecast": { "type": "object", "required": [ "time", "temperature", "rainChance", "precipitationMm", "windSpeed", "windGust", "condition" ], "properties": { "time": { "type": "string" }, "temperature": { "type": [ "number", "null" ] }, "rainChance": { "type": [ "number", "null" ] }, "precipitationMm": { "type": [ "number", "null" ] }, "windSpeed": { "type": [ "number", "null" ] }, "windGust": { "type": [ "number", "null" ] }, "condition": { "type": "string" } } }, "DailyForecast": { "type": "object", "required": [ "date", "weekday", "minimum", "maximum", "rainChance", "precipitationMm", "windGust", "condition" ], "properties": { "date": { "type": "string" }, "weekday": { "type": "string" }, "minimum": { "type": [ "number", "null" ] }, "maximum": { "type": [ "number", "null" ] }, "rainChance": { "type": [ "number", "null" ] }, "precipitationMm": { "type": [ "number", "null" ] }, "windGust": { "type": [ "number", "null" ] }, "condition": { "type": "string" } } }, "Astronomy": { "type": "object", "required": [ "sunrise", "sunset" ], "properties": { "sunrise": { "type": [ "string", "null" ] }, "sunset": { "type": [ "string", "null" ] } } }, "ForecastSource": { "type": "object", "required": [ "provider", "class", "url", "fetchedAt" ], "properties": { "provider": { "type": "string" }, "class": { "type": "string", "const": "forecast" }, "url": { "type": "string", "format": "uri" }, "fetchedAt": { "type": "string", "format": "date-time" } } }, "WeatherResponse": { "type": "object", "required": [ "apiVersion", "city", "data", "sources", "generatedAt", "requestId" ], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "city": { "$ref": "#/components/schemas/CityIdentity" }, "data": { "type": "object", "required": [ "status", "currentForecast", "hourly", "daily", "astronomy", "message" ], "properties": { "status": { "type": "string", "enum": [ "live", "partial", "unavailable" ] }, "currentForecast": { "$ref": "#/components/schemas/WeatherCurrentForecast" }, "hourly": { "type": "array", "items": { "$ref": "#/components/schemas/HourlyForecast" } }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/DailyForecast" } }, "astronomy": { "$ref": "#/components/schemas/Astronomy" }, "message": { "type": [ "string", "null" ] } } }, "sources": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/ForecastSource" } }, "generatedAt": { "type": "string", "format": "date-time" }, "requestId": { "$ref": "#/components/schemas/RequestId" } } }, "AlertItem": { "type": "object", "required": [ "id", "event", "description", "instruction", "severity", "severityLabel", "startsAt", "expiresAt", "officialUrl" ], "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "description": { "type": "string" }, "instruction": { "type": "string" }, "severity": { "type": "string", "enum": [ "potential", "danger", "great-danger", "unknown" ] }, "severityLabel": { "type": "string" }, "startsAt": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ] }, "officialUrl": { "type": "string", "format": "uri" } } }, "AlertSource": { "type": "object", "required": [ "provider", "class", "url", "fetchedAt", "state" ], "properties": { "provider": { "type": "string", "const": "INMET" }, "class": { "type": "string", "const": "alert" }, "url": { "type": "string", "format": "uri" }, "fetchedAt": { "type": "string", "format": "date-time" }, "state": { "type": "string", "enum": [ "live", "unavailable" ] } } }, "AlertsResponse": { "type": "object", "required": [ "apiVersion", "city", "data", "sources", "generatedAt", "requestId" ], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "city": { "$ref": "#/components/schemas/CityIdentity" }, "data": { "type": "object", "required": [ "status", "items", "message" ], "properties": { "status": { "type": "string", "enum": [ "live", "unavailable" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AlertItem" } }, "message": { "type": [ "string", "null" ] } } }, "sources": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/AlertSource" } }, "generatedAt": { "type": "string", "format": "date-time" }, "requestId": { "$ref": "#/components/schemas/RequestId" } } }, "StatusService": { "type": "object", "required": [ "module", "provider", "class", "sourceUrl", "integration", "dataCondition" ], "properties": { "module": { "type": "string", "enum": [ "weather", "alerts" ] }, "provider": { "type": "string" }, "class": { "type": "string", "enum": [ "forecast", "alert" ] }, "sourceUrl": { "type": "string", "format": "uri" }, "integration": { "type": "object", "required": [ "state", "scope", "providerGlobalStatus", "checkedAt", "detail" ], "properties": { "state": { "type": "string", "enum": [ "operational", "partial", "unavailable" ] }, "scope": { "type": "string", "const": "tempo_pelotas" }, "providerGlobalStatus": { "type": "string", "const": "not_assessed" }, "checkedAt": { "type": "string", "format": "date-time" }, "detail": { "type": "string" } } }, "dataCondition": { "type": "object", "required": [ "state", "detail" ], "properties": { "state": { "type": "string", "enum": [ "publishable", "partial", "not_confirmed" ] }, "detail": { "type": "string" } } } } }, "StatusSource": { "type": "object", "required": [ "provider", "class", "url", "checkedAt", "integrationState", "dataCondition", "providerGlobalStatus" ], "properties": { "provider": { "type": "string" }, "class": { "type": "string", "enum": [ "forecast", "alert" ] }, "url": { "type": "string", "format": "uri" }, "checkedAt": { "type": "string", "format": "date-time" }, "integrationState": { "type": "string", "enum": [ "operational", "partial", "unavailable" ] }, "dataCondition": { "type": "string", "enum": [ "publishable", "partial", "not_confirmed" ] }, "providerGlobalStatus": { "type": "string", "const": "not_assessed" } } }, "StatusResponse": { "type": "object", "required": [ "apiVersion", "city", "data", "sources", "generatedAt", "requestId" ], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "city": { "$ref": "#/components/schemas/CityIdentity" }, "data": { "type": "object", "required": [ "checkedAt", "overall", "services" ], "properties": { "checkedAt": { "type": "string", "format": "date-time" }, "overall": { "type": "object", "required": [ "integration", "dataCondition" ], "properties": { "integration": { "type": "string", "enum": [ "operational", "partial", "unavailable" ] }, "dataCondition": { "type": "string", "enum": [ "publishable", "partial", "not_confirmed" ] } } }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/StatusService" } } } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/StatusSource" } }, "generatedAt": { "type": "string", "format": "date-time" }, "requestId": { "$ref": "#/components/schemas/RequestId" } } }, "HydrologyStation": { "type": "object", "required": [ "id", "name", "location", "sourceKey", "verticalReference", "verticalReferenceStatus", "crossSeriesComparable" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "location": { "type": "string" }, "sourceKey": { "type": "string" }, "verticalReference": { "type": [ "string", "null" ] }, "verticalReferenceStatus": { "type": "string", "enum": [ "source_declared", "unknown" ] }, "crossSeriesComparable": { "type": "boolean", "const": false } } }, "HydrologyMeasurement": { "type": "object", "required": [ "value", "unit", "observedAt", "ageMinutes", "trendCmPerHour", "change1hCm", "change6hCm", "change24hCm" ], "properties": { "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "enum": [ "m", "cm" ] }, "observedAt": { "type": [ "string", "null" ] }, "ageMinutes": { "type": [ "number", "null" ] }, "trendCmPerHour": { "type": [ "number", "null" ] }, "change1hCm": { "type": [ "number", "null" ] }, "change6hCm": { "type": [ "number", "null" ] }, "change24hCm": { "type": [ "number", "null" ] } } }, "HydrologyThreshold": { "type": "object", "required": [ "kind", "value", "unit", "reference" ], "properties": { "kind": { "type": "string", "enum": [ "flood", "may_2024_maximum" ] }, "value": { "type": "number" }, "unit": { "type": "string", "const": "cm" }, "reference": { "type": "string" } } }, "HydrologySource": { "type": "object", "required": [ "provider", "class", "url", "fetchedAt", "organizations", "verticalReference", "verticalReferenceStatus", "crossSeriesComparable" ], "properties": { "provider": { "type": "string" }, "class": { "type": "string", "const": "hydrology" }, "url": { "type": "string", "format": "uri" }, "fetchedAt": { "type": "string", "format": "date-time" }, "organizations": { "type": [ "string", "null" ] }, "verticalReference": { "type": [ "string", "null" ] }, "verticalReferenceStatus": { "type": "string", "enum": [ "source_declared", "unknown" ] }, "crossSeriesComparable": { "type": "boolean", "const": false } } }, "HydrologyResponse": { "type": "object", "required": [ "apiVersion", "city", "data", "sources", "generatedAt", "requestId" ], "properties": { "apiVersion": { "$ref": "#/components/schemas/ApiVersion" }, "city": { "$ref": "#/components/schemas/CityIdentity" }, "data": { "type": "object", "required": [ "status", "dataCondition", "station", "measurement", "thresholds", "message" ], "properties": { "status": { "type": "string", "enum": [ "live", "stale", "unavailable" ] }, "dataCondition": { "type": "string", "enum": [ "publishable", "stale", "not_confirmed" ] }, "station": { "$ref": "#/components/schemas/HydrologyStation" }, "measurement": { "$ref": "#/components/schemas/HydrologyMeasurement" }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/HydrologyThreshold" } }, "message": { "type": [ "string", "null" ] } } }, "sources": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/HydrologySource" } }, "generatedAt": { "type": "string", "format": "date-time" }, "requestId": { "$ref": "#/components/schemas/RequestId" } } }, "ApiError": { "type": "object", "required": [ "error", "requestId" ], "properties": { "apiVersion": { "type": "string", "const": "v1" }, "error": { "type": "string", "enum": [ "invalid_api_key", "insufficient_scope", "client_inactive", "client_invalid", "pro_required", "rate_limit_exceeded", "api_unavailable", "city_not_found", "weather_unavailable", "alerts_unavailable", "status_unavailable", "hydrology_not_supported", "hydrology_unavailable" ] }, "requiredScope": { "type": "string", "enum": [ "cities:read", "weather:read", "alerts:read", "hydrology:read", "status:read" ] }, "city": { "type": "object", "required": [ "id", "slug", "name" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" } } }, "requestId": { "$ref": "#/components/schemas/RequestId" } } } } } }