# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.gospace.com/start-building/optimise-your-first-location.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.