Skip to main content

Endpoint

POST /guardar
Uploads a vehicle image, extracts the license plate using OCR (GPT-4o-mini + Tesseract fallback), and saves the record to the CSV database.

Request Parameters

This endpoint accepts multipart/form-data with the following fields:
imagen
file
required
Image file containing a vehicle license plate. Supported formats: JPG, JPEG, PNG. The image is saved with a timestamped filename in the format matricula_YYYYMMDD_HHMMSS.jpg.
propietario
string
Name of the vehicle owner. Optional field that can be left empty.
tipo_vehiculo
string
Type of vehicle (e.g., “Sedan”, “SUV”, “Motorcycle”, “Truck”). Optional field.
observacion
string
Additional notes or observations about the vehicle or registration. Optional field.

OCR Process

The endpoint uses a two-stage OCR process:

Stage 1: GPT-4o-mini Vision

The image is base64-encoded and sent to OpenAI’s GPT-4o-mini model with the prompt:
“Extrae únicamente el texto de la matrícula visible en esta imagen (placa de vehículo). Devuelve solo la matrícula, sin texto adicional, comentarios ni símbolos extras.”
The extracted text is:
  • Converted to uppercase
  • Cleaned to contain only alphanumeric characters and hyphens
  • Truncated to 10 characters maximum

Stage 2: Tesseract Fallback

If GPT-4o returns “NO_DETECTADA”, the system falls back to Tesseract OCR:
image = Image.open(path)
ocr_text = pytesseract.image_to_string(image, lang="eng")
The same cleaning rules are applied to the Tesseract output.

Response

The endpoint returns an HTTP 302 redirect to the home page (/) with a flash message.

Success Response

Status Code: 302 Found Location: / Flash Message: ✅ Registro guardado correctamente (category: ok) A new record is added to data/registros.csv with:
  • Auto-generated ID (sequential)
  • Current timestamp
  • Extracted license plate number
  • Provided owner, vehicle type, and observations
  • Saved image filename

Error Response

Status Code: 302 Found Location: / Flash Message: ⚠️ Debes subir una imagen (category: error) This occurs when no image file is provided in the request.

Request Examples

curl -X POST http://localhost:5000/guardar \
  -F "imagen=@/path/to/vehicle_plate.jpg" \
  -F "propietario=Juan Pérez" \
  -F "tipo_vehiculo=Sedan" \
  -F "observacion=Vehículo de entrega"

CSV Record Structure

After successful upload, a new row is appended to data/registros.csv:
id,fecha_hora,matricula,propietario,tipo_vehiculo,observacion,imagen
1,2026-03-04 15:30:45,ABC1234,Juan Pérez,Sedan,Vehículo de entrega,matricula_20260304_153045.jpg

Image Storage

Uploaded images are saved in the uploads/ directory with the naming pattern:
matricula_YYYYMMDD_HHMMSS.jpg
Example: matricula_20260304_153045.jpg Images can be accessed via the /uploads/<filename> endpoint.

Error Scenarios

Missing Image File: If the imagen field is empty or not provided, the request fails with an error flash message and redirects to home.
OCR Failure: If both GPT-4o and Tesseract fail to extract a plate, the matricula field is set to the last cleaned OCR attempt or “NO_DETECTADA”.
Invalid Image Format: If the uploaded file cannot be processed by PIL (Pillow), the Tesseract fallback may fail, but the record is still saved with the GPT-4o result.

Best Practices

  1. Image Quality: Use high-resolution images with clear visibility of the license plate for best OCR results
  2. File Size: Keep image files under 10MB for optimal processing speed
  3. Lighting: Ensure the plate is well-lit and not obscured by shadows or glare
  4. Angle: Front-facing or rear-facing shots work best; avoid extreme angles
  5. Error Handling: Always check the flash message after redirect to confirm success

View Records

See all uploaded records

Delete Record

Remove an uploaded record

Build docs developers (and LLMs) love