{
  "openapi": "3.1.0",
  "info": {
    "title": "Atlas Maps API",
    "version": "1.1.0-beta",
    "description": "Server-to-server beta. 60 admitted calls/minute and 1000/day UTC per account, shared by all keys. Admitted requests count even when an upstream fails; authentication, parameter and quota rejections do not. Maximum 5 active keys, valid for 90 days. Coordinate coverage: longitude 7.4–11.7, latitude 30.2–37.7; Tunisian data coverage is partial. No automatic billing or availability SLA. Display response attribution with results. Use a secret Bearer key on your server, never in a public application bundle. No public CORS. API errors are English machine-readable messages; source names are preserved. Send an explicit identifying User-Agent such as MonApp/1.0. The hosting edge may reject default automated client identifiers (including Python-urllib) with HTTP 403 before API authentication."
  },
  "servers": [
    {
      "url": "https://atlastunisie.com/api/maps/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/places": {
      "get": {
        "operationId": "places",
        "summary": "Search Tunisian catalogue places, streets and recorded addresses",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "3 to 100 searchable characters",
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 100,
              "example": "La Marsa"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful query; an empty data array is a valid search result.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-DailyLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Place"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "request_id": {
                          "type": "string"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "catalogue_updated_at": {
                          "type": "string"
                        },
                        "match_type": {
                          "type": "string"
                        },
                        "exact_address_guaranteed": {
                          "const": false
                        },
                        "search_strategy": {
                          "type": "string",
                          "enum": [
                            "normalized_tokens",
                            "approximate_fallback"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, expired or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient key scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Account quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Catalogue or routing unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying a temporary service failure.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/reverse": {
      "get": {
        "operationId": "reverse",
        "summary": "Find the nearest recorded feature; not guaranteed reverse postal geocoding",
        "parameters": [
          {
            "name": "point",
            "in": "query",
            "required": true,
            "description": "WGS84 longitude,latitude",
            "schema": {
              "type": "string",
              "example": "10.1815,36.8065",
              "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$"
            }
          },
          {
            "name": "radius",
            "in": "query",
            "required": false,
            "description": "Search radius in meters",
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 5000,
              "default": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful query; an empty data array is a valid search result.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-DailyLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Place"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "request_id": {
                          "type": "string"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "catalogue_updated_at": {
                          "type": "string"
                        },
                        "match_type": {
                          "type": "string"
                        },
                        "exact_address_guaranteed": {
                          "const": false
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, expired or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient key scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Account quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Catalogue or routing unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying a temporary service failure.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/directions": {
      "get": {
        "operationId": "directions",
        "summary": "Calculate a driving route without real-time traffic",
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "required": true,
            "description": "WGS84 longitude,latitude; at least 10 meters from end",
            "schema": {
              "type": "string",
              "example": "10.1815,36.8065",
              "pattern": "^-?\\d+(\\.\\d+)?,-?\\d+(\\.\\d+)?$"
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": true,
            "description": "WGS84 longitude,latitude",
            "schema": {
              "type": "string",
              "example": "10.3253,36.8782"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A validated driving route with distance, duration and geometry.",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-DailyLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "profile": {
                          "const": "car"
                        },
                        "distance_m": {
                          "type": "number",
                          "minimum": 0
                        },
                        "duration_s": {
                          "type": "number",
                          "minimum": 0
                        },
                        "traffic": {
                          "const": "not_included"
                        },
                        "geometry": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "const": "LineString"
                            },
                            "coordinates": {
                              "type": "array",
                              "items": {
                                "type": "array",
                                "items": {
                                  "type": "number"
                                },
                                "minItems": 2,
                                "maxItems": 2
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "request_id": {
                          "type": "string"
                        },
                        "attribution": {
                          "type": "string"
                        },
                        "catalogue_updated_at": {
                          "type": "string"
                        },
                        "match_type": {
                          "type": "string"
                        },
                        "exact_address_guaranteed": {
                          "const": false
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, expired or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient key scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Account quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying",
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Catalogue or routing unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "Minimum delay in seconds before retrying a temporary service failure.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Private atlas_maps_ key from /developpeurs"
      }
    },
    "schemas": {
      "Place": {
        "type": "object",
        "required": [
          "id",
          "name",
          "context",
          "kind",
          "coordinates"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "alternate_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "context": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "description": "Catalogue type: poi, address, street, locality or another source type. Never implies an exact postal address."
          },
          "category": {
            "type": "string"
          },
          "coordinates": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "minItems": 2,
            "maxItems": 2,
            "description": "WGS84 [longitude, latitude]"
          },
          "distance_m": {
            "type": "number",
            "description": "Only returned for reverse: distance to the input point."
          },
          "match_quality": {
            "type": "string",
            "enum": [
              "exact_name",
              "name_prefix",
              "terms",
              "approximate"
            ],
            "description": "Places only. Match after normalization and a bounded French/Tunisian name alias list; approximate is a one-edit fallback only when no direct matches exist. Not a confidence score or exact address guarantee."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "request_id"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
