{
    "openapi": "3.1.0",
    "info": {
        "title": "API de Mapas",
        "version": "v1",
        "description": "Busca de endereços, geocodificação e cálculo de rotas em uma única interface."
    },
    "servers": [
        {
            "url": "https://api.flowdata.one/v1",
            "description": "FlowData API"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "search",
            "description": "Busca de locais"
        },
        {
            "name": "geocoding",
            "description": "Geocodificação"
        },
        {
            "name": "routing",
            "description": "Rotas"
        }
    ],
    "paths": {
        "/maps/search": {
            "get": {
                "operationId": "maps-search",
                "summary": "Buscar endereços e lugares",
                "description": "Busca endereços e lugares. Um resultado já existente é entregue pelo nosso próprio banco de dados, sem consultar um serviço de mapas. Uma busca sem resultado não é cobrada.",
                "tags": [
                    "search"
                ],
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "description": "Termo de busca, até 256 caracteres",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Quantidade de resultados, 1 a 10, padrão 10",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "description": "Filtro de país, ISO 3166-1 alpha-2, por exemplo BR",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "Idioma dos resultados, padrão de",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "proximity",
                        "in": "query",
                        "required": false,
                        "description": "Local preferido como lng,lat",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "types",
                        "in": "query",
                        "required": false,
                        "description": "Tipos de resultado; a requisição vai direto para a Mapbox",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "success": true,
                                    "addresses": [
                                        {
                                            "full_address": "Berlin, Deutschland",
                                            "lat": 52.5200066,
                                            "lng": 13.404954,
                                            "place_name": "Berlin",
                                            "postcode_name": "10115",
                                            "country_name": "Deutschland",
                                            "country_code": "DE"
                                        }
                                    ],
                                    "attribution": "NOTICE: © 2026 FlowSuite and its suppliers. All rights reserved. Use of this data is subject to the Terms of Service (https://creativeskyline.de/agb). This response and the information it contains may not be retained."
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/maps/geocode": {
            "get": {
                "operationId": "maps-geocode",
                "summary": "Resolver endereço ou coordenadas",
                "description": "Transforma um endereço em coordenadas e dados completos de endereço, ou coordenadas de volta em endereço. Somente uma resposta bem-sucedida é cobrada; 404 sem resultado é grátis.",
                "tags": [
                    "geocoding"
                ],
                "parameters": [
                    {
                        "name": "address",
                        "in": "query",
                        "required": false,
                        "description": "Endereço para a busca direta",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "lng",
                        "in": "query",
                        "required": false,
                        "description": "Longitude para a busca reversa, junto com lat",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "lat",
                        "in": "query",
                        "required": false,
                        "description": "Latitude para a busca reversa, junto com lng",
                        "schema": {
                            "type": "number"
                        }
                    },
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "description": "Filtro de país, ISO 3166-1 alpha-2",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "Idioma dos resultados, padrão de",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "success": true,
                                    "address": {
                                        "full_address": "Friedrichstraße 43, 10117 Berlin, Deutschland",
                                        "lat": 52.5094,
                                        "lng": 13.3889,
                                        "place_name": "Berlin",
                                        "postcode_name": "10117",
                                        "country_name": "Deutschland",
                                        "country_code": "DE"
                                    },
                                    "attribution": "NOTICE: © 2026 FlowSuite and its suppliers. All rights reserved. Use of this data is subject to the Terms of Service (https://creativeskyline.de/agb). This response and the information it contains may not be retained."
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/maps/directions": {
            "get": {
                "operationId": "maps-directions",
                "summary": "Calcular rota",
                "description": "Calcula uma rota entre dois ou mais pontos, com distância, duração e geometria. Somente uma resposta bem-sucedida é cobrada; 404 sem rota é grátis.",
                "tags": [
                    "routing"
                ],
                "parameters": [
                    {
                        "name": "origin",
                        "in": "query",
                        "required": true,
                        "description": "Ponto de partida como lng,lat, por exemplo 13.4050,52.5200",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "destination",
                        "in": "query",
                        "required": true,
                        "description": "Destino como lng,lat",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "profile",
                        "in": "query",
                        "required": false,
                        "description": "driving, driving-traffic, walking ou cycling, padrão driving-traffic",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "waypoints",
                        "in": "query",
                        "required": false,
                        "description": "Paradas como lng,lat, separadas por |",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "language",
                        "in": "query",
                        "required": false,
                        "description": "Idioma das instruções, padrão de",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Resposta bem-sucedida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                },
                                "example": {
                                    "success": true,
                                    "routes": [
                                        {
                                            "distance": 3120.4,
                                            "duration": 540.2,
                                            "legs": [
                                                {
                                                    "distance": 3120.4,
                                                    "duration": 540.2
                                                }
                                            ]
                                        }
                                    ],
                                    "attribution": "NOTICE: © 2026 FlowSuite and its suppliers. All rights reserved. Use of this data is subject to the Terms of Service (https://creativeskyline.de/agb). This response and the information it contains may not be retained."
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "Resposta de erro",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Chave FlowData como Authorization: Bearer fd_…"
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "message": {
                                "type": "string"
                            },
                            "type": {
                                "type": "string"
                            },
                            "details": {
                                "type": "object"
                            }
                        }
                    }
                }
            }
        }
    }
}