# Optimise your first location

Trigger the AI to evolve your location layout based on forecasts and settings, dynamically assigning spaces to teams and people.

{% tabs %}
{% tab title="Node.js" %}

### Prerequisites

* Completed **Add historic attendance** and **Start forecasting**
* Node.js v18+ and npm v9+
* A valid gospace API key in your `.env` file
* A **location\_id** with recent forecasts available

{% hint style="info" %}
The evolution process uses your forecasts and configuration to create dynamic **allocations** (teams/people → space types). These adjust over time (daily, weekly, bi‑weekly, monthly, quarterly) according to your setup.
{% endhint %}

***

### 1) Choose evolution settings

* **date** — the effective date (YYYY‑MM‑DD) you want to evolve.
* **disruption** — how much change you’re willing to accept:
  * `MIN` – smallest movement; preserve stability.
  * `MAX` – full optimisation; least stable.
* **run\_by\_zone** — `true` to evolve zone‑by‑zone (useful when zones are meaningful capacity containers), `false` to evolve the whole location at once.

***

### 2) Trigger evolution

Create `evolve-location.ts`:

```ts
import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  const res = await gospace.system.evolveLocation({
    location_id: "68824ca5369c856b7c670510",
    date: "2025-08-08",
    settings: {
      disruption: "MIN",   // 'MIN' | 'MAX'
      run_by_zone: false,  // evolve entire location in one pass
    },
  });

  // Expect: { success, data: { evolution_id, status }, identifier }
  console.log(JSON.stringify(res.data, null, 2));
}

main().catch((err) => {
  console.error("Trigger evolve failed:", err);
  process.exit(1);
});
```

***

### 3) Poll status until completion

Create `evolve-status.ts`:

```ts
import "dotenv/config";
import GospaceAI from "@gospace-ai/api";

const EVOLUTION_ID = process.env.EVOLUTION_ID!; // set from step 2 response

async function main() {
  const gospace = new GospaceAI(process.env.GOSPACE_API_KEY!);

  for (;;) {
    const res = await gospace.system.getEvolutionStatus({
      evolution_id: EVOLUTION_ID,
    });

    const status = res.data.status; // 'created' | 'processing' | 'no_execution' | 'successful' | 'failed'
    console.log(`[evolve] status: ${status}`);

    if (status === "successful" || status === "no_execution") break;
    if (status === "failed") throw new Error("Evolution failed");
    await new Promise((r) => setTimeout(r, 3000));
  }

  console.log("Evolution complete.");
}

main().catch((err) => {
  console.error("Check evolve status failed:", err);
  process.exit(1);
});
```

Run:

```bash
EVOLUTION_ID="94289524-04ac-44d3-8f05-45b8a937f663" npx tsx evolve-status.ts
```

***

### 4) Interpreting the results

After a **successful** evolution:

* The system produces **allocations** that map **teams/people** to **space types** (e.g., desks, rooms) for the requested date.
* Allocations are driven by your **forecast** (including `*_inc` adjustments for minimum targets, bookings/intentions, and contingencies) and your **settings** (`disruption`, `run_by_zone`).
* These allocations **grow/shrink dynamically** as forecasts change and as you re‑run evolution on your chosen cadence (daily/weekly/bi‑weekly/monthly/quarterly).

{% hint style="info" %}
If your evolution returns **`no_execution`**, it means there were no material changes to apply given the current forecasts and settings. Consider increasing `disruption`, adjusting forecasts/targets, or running by zones.
{% endhint %}
{% endtab %}
{% endtabs %}