Skip to main content

MapFirstCore API

Core JavaScript API for MapFirst SDK. Works in both React and vanilla JavaScript environments.

Import​

// ES Modules
import { MapFirstCore } from "@mapfirst/core";

// Browser (CDN)
const { MapFirstCore } = window.MapFirstCore;

Constructor​

new MapFirstCore(config);

Parameters​

interface MapFirstConfig {
  adapter: any | null;
  initialLocationData?: {
    city?: string;
    country?: string;
    currency?: string;
  };
  environment?: "dev" | "prod";
  callbacks?: {
    onPropertiesChange?: (properties: Property[]) => void;
    onSelectedPropertyChange?: (id: number | null) => void;
    onBoundsChange?: (bounds: Bounds) => void;
    onSearchingStateChange?: (isSearching: boolean) => void;
    onError?: (error: Error) => void;
  };
}

Example​

const mapFirst = new MapFirstCore({
  adapter: null,
  initialLocationData: {
    city: "Paris",
    country: "France",
    currency: "EUR",
  },
  environment: "prod",
  callbacks: {
    onPropertiesChange: (properties) => {
      console.log("Properties updated:", properties);
    },
  },
});

Methods​

attachMap​

Attach a map instance to MapFirst.

attachMap(map: any, options: AttachMapOptions): void

Parameters:

interface AttachMapOptions {
  platform: "maplibre" | "mapbox" | "google";
  maplibregl?: typeof maplibregl; // Required for MapLibre
  mapboxgl?: typeof mapboxgl; // Required for Mapbox
  google?: typeof google; // Required for Google Maps
  onMarkerClick?: (property: Property) => void;
}

Example:

// MapLibre
mapFirst.attachMap(map, {
  platform: "maplibre",
  maplibregl: maplibregl,
  onMarkerClick: (property) => {
    alert(property.name);
  },
});

// Google Maps
mapFirst.attachMap(map, {
  platform: "google",
  google: window.google,
});

runPropertiesSearch​

Search for properties by location.

runPropertiesSearch(params: SearchParams): Promise<void>

Example:

await mapFirst.runPropertiesSearch({
  body: {
    city: "London",
    country: "United Kingdom",
    filters: {
      checkIn: "2024-07-01",
      checkOut: "2024-07-05",
      numAdults: 2,
      currency: "GBP",
    },
  },
});

runSmartFilterSearch​

AI-powered natural language search.

runSmartFilterSearch(params: SmartSearchParams): Promise<void>

Example:

await mapFirst.runSmartFilterSearch({
  query: "romantic restaurants with outdoor seating",
  city: "Rome",
  country: "Italy",
});

performBoundsSearch​

Search within current map bounds.

performBoundsSearch(): Promise<void>

Example:

await mapFirst.performBoundsSearch();

setPrimaryType​

Set the property type filter.

setPrimaryType(type: 'Accommodation' | 'Restaurant' | 'Attraction'): void

Example:

mapFirst.setPrimaryType("Attraction");

setSelectedMarker​

Select or deselect a property.

setSelectedMarker(id: number | null): void

Example:

// Select
mapFirst.setSelectedMarker(12345);

// Deselect
mapFirst.setSelectedMarker(null);

flyMapTo​

Animate map to a location.

flyMapTo(lng: number, lat: number, zoom?: number): void

Example:

// Fly to Eiffel Tower
mapFirst.flyMapTo(2.2945, 48.8584, 15);

getState​

Get current state snapshot.

getState(): MapFirstState

Example:

const state = mapFirst.getState();
console.log("Current properties:", state.properties);
console.log("Is searching:", state.isSearching);

destroy​

Clean up resources.

destroy(): void

Example:

mapFirst.destroy();

Events / Callbacks​

All callbacks are optional and passed during initialization.

onPropertiesChange​

Called when properties are updated.

onPropertiesChange?: (properties: Property[]) => void

onSelectedPropertyChange​

Called when selection changes.

onSelectedPropertyChange?: (id: number | null) => void

onBoundsChange​

Called when map bounds change.

onBoundsChange?: (bounds: Bounds) => void

onSearchingStateChange​

Called when search state changes.

onSearchingStateChange?: (isSearching: boolean) => void

onError​

Called when an error occurs.

onError?: (error: Error) => void

Types​

Property​

interface Property {
  id: number;
  name: string;
  location: {
    lat: number;
    lng: number;
  };
  rating?: number;
  price?: number;
  currency?: string;
  type: "Accommodation" | "Restaurant" | "Attraction";
  address?: string;
  photos?: string[];
  amenities?: string[];
}

Bounds​

interface Bounds {
  north: number;
  south: number;
  east: number;
  west: number;
}

See Also​