Documentación del Paquete Autocompleter

Este paquete proporciona funcionalidades para obtener sugerencias e información para direcciones y sitios de interés de la Ciudad de Buenos Aires.

Instalación

Para instalar el paquete, utilizar npm:

npm install autocompleter-caba

Uso

Importar el paquete:

// Para módulos ES6/TypeScript
import { Autocompleter } from "autocompleter-caba";

// Para CommonJS (Node.js)
const { Autocompleter } = require("autocompleter-caba");

Crear una instancia de Autocompleter:

const autocompleter = new Autocompleter();

Configuración de Credenciales

Vía Headers

Establecer las credenciales del cliente utilizando el método setCredentials(clientId, clientSecret):

autocompleter.setCredentials("tu_client_id", "tu_client_secret");

Vía Basic Authorization

También es posible enviar las credenciales mediante Basic Auth (Authorization: Basic <(clientId:clientSecret)>). Cambia el modo a basic con setAuthMode y reutiliza setCredentials. El modo predeterminado es headers, que envía client_id y client_secret como headers separados. Si ya configuraste credenciales y luego cambias el modo, el paquete vuelve a propagarlas automáticamente.

import { Autocompleter } from "autocompleter-caba";

const autocompleter = new Autocompleter();
autocompleter.setAuthMode("basic"); // por defecto es "headers"
autocompleter.setCredentials("tu_client_id", "tu_client_secret");

Clon de compatibilidad con Basic Auth encriptado

Se mantiene el clon NeoAutocompleter para quienes prefieran instanciar directamente con Basic Auth habilitado.

import { NeoAutocompleter } from "autocompleter-caba";

const neoAutocompleter = new NeoAutocompleter();
neoAutocompleter.setCredentials("tu_client_id", "tu_client_secret");

El resto de los métodos y funcionalidades se mantienen sin cambios.

Habilitar/Desactivar Suggesters

Se puede habilitar o desactivar los suggesters (buscadores de direcciones o lugares) según necesidades utilizando los métodos enableSuggester(suggester) y disableSuggester(suggester):

import { SuggestersOptions } from "autocompleter-caba"; // Asegurarse de importar SuggestersOptions si se usa TS/ES6

// Habilitar solo búsqueda de direcciones
autocompleter.enableSuggester(SuggestersOptions.AddressSuggester);
autocompleter.disableSuggester(SuggestersOptions.PlaceSuggester);

// Habilitar ambos (comportamiento por defecto)
autocompleter.enableSuggester(SuggestersOptions.AddressSuggester);
autocompleter.enableSuggester(SuggestersOptions.PlaceSuggester);

Obtener Sugerencias

Para obtener sugerencias de autocompletado basadas en la entrada del usuario, utilizar el método getSuggestions(input, typeSuggester):

// Obtener sugerencias de direcciones y lugares
const suggestionsAll = await autocompleter.getSuggestions("all");
console.log(suggestionsAll);

// Obtener solo sugerencias de direcciones
const suggestionsAddr = await autocompleter.getSuggestions("address");
console.log(suggestionsAddr);

// Obtener solo sugerencias de lugares
const suggestionsPlace = await autocompleter.getSuggestions("place");
console.log(suggestionsPlace);

Buscar Información Detallada

Búsqueda General

Para buscar información detallada (coordenadas, etc.) a partir de una cadena de texto (que puede ser una dirección o un lugar), usar getSearch(input):

// Intentará buscar la mejor coincidencia (dirección o lugar)
const searchResult = await autocompleter.getSearch("Callao 520");
console.log(searchResult);

const searchPlaceResult = await autocompleter.getSearch("Hospital Italiano");
console.log(searchPlaceResult);

Búsqueda Específica de Direcciones

Para buscar información detallada de una dirección específica, utilizar getSearchAddress(address). Este método permite filtrar por método de geocodificación si se ha configurado previamente.

Búsqueda Específica de Lugares

Para buscar información detallada de un lugar específico, utilizar getSearchPlaces(place):

const searchPlaceResult = await autocompleter.getSearchPlaces("Planetario");
console.log(searchPlaceResult);

Métodos Disponibles

Las siguientes funciones están disponibles y pueden ser utilizadas para interactuar con el paquete:

• getClientId(): string: Devuelve el clientId configurado.
• getClientSecret(): string: Devuelve el clientSecret configurado.
• getConfigurations(): object: Devuelve la configuración actual (minTextLength, waitingTime, maxSuggestions).
• setConfigurations(minTextLength: number, waitingTime: number, maxSuggestions: number): void: Establece la configuración de longitud mínima de texto para sugerencias, tiempo de espera (debounce) y número máximo de sugerencias.
• setCredentials(clientId: string, clientSecret: string): void: Establece las credenciales (clientId, clientSecret) necesarias para las llamadas API.
• setAuthMode(mode: "headers" | "basic"): void: Define cómo se envían las credenciales. "headers" (valor por defecto) usa los headers client_id y client_secret. "basic" envía Authorization: Basic <code>.
• setApiBaseUrl(baseUrl: string): void: Permite cambiar la URL base de la API. Por defecto: "<https://datosabiertos-callejeros-apis.buenosaires.gob.ar/>".
• findSuggester(suggesterType: SuggestersOptions): Suggester | undefined: Busca y devuelve una instancia de Suggester según el tipo.
• enableSuggester(suggester: SuggestersOptions): void: Habilita un Suggester específico (Address o Place).
• disableSuggester(suggester: SuggestersOptions): void: Desactiva un Suggester específico.
• getSuggesters(): object: Devuelve un objeto con las instancias de los Suggesters disponibles.
• getSuggestions(input: string, typeSuggester?: "all" | "address" | "place"): Promise<Array<object>>: Obtiene una lista de sugerencias normalizadas basadas en el input. typeSuggester filtra el tipo ('address', 'place', o 'all' por defecto).
• getSearch(input: string | object): Promise<object>: Realiza una búsqueda detallada a partir de un input (string) o una sugerencia (object). Intenta determinar si es dirección o lugar.
• getSearchPlaces(place: string | object): Promise<object>: Realiza una búsqueda detallada específica para lugares.
• getSearchAddress(address: string | object): Promise<object>: Realiza una búsqueda detallada específica para direcciones. Importante: Esta función ahora respeta los métodos de geocodificación configurados mediante setGeocodingMethods.
• setGeocodingMethods(methods: string[]): void: Define uno o más métodos de geocodificación permitidos al usar getSearchAddress. Si se proporciona un array no vacío, el filtro se activa implícitamente. Un array vacío desactiva el filtro. Los valores posibles para methods son strings que representan los labels de los métodos:
  • "Geocodificacion Directa"
  • "Interpolacion entre Puertas"
  • "Interseccion entre Calles"
  • "Interpolacion sobre Eje"
  • "Direccion Atipica"

Nota: La API debe soportar el filtrado por método para que esto tenga efecto.

• getGeocodingMethods(): string[]: Devuelve el array de labels de métodos de geocodificación actualmente configurados para el filtro.
• getAllGeocodingMethods(): GeocodingMethod[]: Devuelve un array de objetos { value: string, label: string } con todos los métodos de geocodificación disponibles definidos en el paquete.
• getAllGeocodingMethodsValues(): string[]: Devuelve un array con solo los value de todos los métodos disponibles.
• getAllGeocodingMethodsLabels(): string[]: Devuelve un array con solo los label de todos los métodos disponibles (útil para configurar setGeocodingMethods).

Ejemplos de Uso

React

import { Autocompleter } from "autocompleter-caba";
import React, { useEffect, useState, useMemo } from "react";

function App() {
  const [input, setInput] = useState("");

  // Instancia única con useMemo
  const autocompleter = useMemo(() => new Autocompleter(), []);

  useEffect(() => {
    // Configuración inicial
    autocompleter.setCredentials("CLIENT_ID", "CLIENT_SECRET");
    // Opcional: Cambiar URL base
    // autocompleter.setApiBaseUrl("<http://localhost:8000/>");
    // Opcional: Establecer métodos de geocodificación permitidos
    autocompleter.setGeocodingMethods(["Geocodificacion Directa"]);
    console.log(
      "Métodos geocodificación permitidos:",
      autocompleter.getGeocodingMethods()
    );
  }, [autocompleter]);

  const handleGetSuggestions = async () => {
    console.log(`Buscando sugerencias para: ${input}`);
    const suggestions = await autocompleter.getSuggestions(input);
    console.log("Sugerencias:", suggestions);
  };

  const handleSearchAddress = async () => {
    console.log(`Buscando dirección: ${input}`);
    // Usará los métodos configurados en setGeocodingMethods si la API lo soporta
    const result = await autocompleter.getSearchAddress(input);
    console.log("Resultado Búsqueda Dirección:", result);
  };

  const handleSearchPlace = async () => {
    console.log(`Buscando lugar: ${input}`);
    const result = await autocompleter.getSearchPlaces(input);
    console.log("Resultado Búsqueda Lugar:", result);
  };

  return (
    <div>
      <input
        type="text"
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder="Ingrese dirección o lugar"
      />
      <button onClick={handleGetSuggestions}>Obtener Sugerencias</button>
      <button onClick={handleSearchAddress}>Buscar Dirección</button>
      <button onClick={handleSearchPlace}>Buscar Lugar</button>
      <p>Revisar la consola del navegador para ver los resultados.</p>
    </div>
  );
}

export default App;

Angular

import { Component, OnInit } from "@angular/core";
import { Autocompleter } from "autocompleter-caba";
import { FormsModule } from "@angular/forms"; // Necesario importar FormsModule para ngModel
import { CommonModule } from "@angular/common"; // Necesario CommonModule

@Component({
  selector: "app-root",
  standalone: true,
  imports: [FormsModule, CommonModule],
  template: `
    <div>
      <input [(ngModel)]="input" placeholder="Ingrese dirección o lugar" />
      <button (click)="getSuggestions()">Obtener Sugerencias</button>
      <button (click)="searchAddress()">Buscar Dirección</button>
      <button (click)="searchPlace()">Buscar Lugar</button>
      <p>Revisa la consola del navegador para ver los resultados.</p>
    </div>
  `,
})
export class AppComponent implements OnInit {
  input = "Callao 520";
  autocompleter: Autocompleter;

  constructor() {
    this.autocompleter = new Autocompleter();
  }

  ngOnInit() {
    this.autocompleter.setCredentials("CLIENT_ID", "CLIENT_SECRET");
    // Opcional: Cambiar URL base
    // this.autocompleter.setApiBaseUrl("<http://localhost:8000/>");
    // Opcional: Establecer métodos de geocodificación permitidos
    this.autocompleter.setGeocodingMethods(["geocodificacion_directa"]);
    console.log(
      "Métodos geocodificación permitidos:",
      this.autocompleter.getGeocodingMethods()
    );
  }

  async getSuggestions() {
    console.log(`Buscando sugerencias para: ${this.input}`);
    const suggestions = await this.autocompleter.getSuggestions(this.input);
    console.log("Sugerencias:", suggestions);
  }

  async searchAddress() {
    console.log(`Buscando dirección: ${this.input}`);
    const result = await this.autocompleter.getSearchAddress(this.input);
    console.log("Resultado Búsqueda Dirección:", result);
  }

  async searchPlace() {
    console.log(`Buscando lugar: ${this.input}`);
    const result = await this.autocompleter.getSearchPlaces(this.input);
    console.log("Resultado Búsqueda Lugar:", result);
  }
}

HTML/JS (sin Bundler)

<!DOCTYPE html>
<html>
  <head>
    <title>Autocompleter CABA Demo</title>
  </head>
  <body>
    <h1>Autocompleter CABA Demo</h1>
    <input
      id="inputField"
      placeholder="Ingrese dirección o lugar"
      value="Callao 520"
    />
    <button onclick="getSuggestions()">Obtener Sugerencias</button>
    <button onclick="searchAddress()">Buscar Dirección</button>
    <button onclick="searchPlace()">Buscar Lugar</button>
    <p>Revisa la consola del navegador para ver los resultados.</p>

    <!-- Cargar la librería desde unpkg -->
    <script src="<https://unpkg.com/autocompleter-caba@latest/dist/umd/autocompleter.umd.js>"></script>
    <script>
      const inputField = document.getElementById("inputField");

      // Asume que Autocompleter está en el scope global
      const autocompleter = new Autocompleter();

      // Configuración inicial
      autocompleter.setCredentials("CLIENT_ID", "CLIENT_SECRET");
      // Opcional: Cambiar URL base
      // autocompleter.setApiBaseUrl("<http://localhost:8000/>");
      // Opcional: Establecer métodos de geocodificación permitidos
      autocompleter.setGeocodingMethods(["geocodificacion_directa"]);
      console.log(
        "Métodos geocodificación permitidos:",
        autocompleter.getGeocodingMethods()
      );

      async function getSuggestions() {
        const value = inputField.value;
        console.log(`Buscando sugerencias para: ${value}`);
        const suggestions = await autocompleter.getSuggestions(value);
        console.log("Sugerencias:", suggestions);
      }

      async function searchAddress() {
        const value = inputField.value;
        console.log(`Buscando dirección: ${value}`);
        const result = await autocompleter.getSearchAddress(value);
        console.log("Resultado Búsqueda Dirección:", result);
      }

      async function searchPlace() {
        const value = inputField.value;
        console.log(`Buscando lugar: ${value}`);
        const result = await autocompleter.getSearchPlaces(value);
        console.log("Resultado Búsqueda Lugar:", result);
      }
    </script>
  </body>
</html>

Notas Adicionales

• Asegurarse de establecer las credenciales del cliente antes de realizar cualquier búsqueda.
• Los suggesters deben estar habilitados antes de utilizar las funciones de búsqueda correspondientes.
• El paquete tiene restricciones en cuanto a la longitud mínima de texto y el número máximo de sugerencias.
• Filtrado por Método: setGeocodingMethods solo tiene efecto si la API conectada soporta este filtrado y devuelve el campo metodo_geocodificacion.