> ## Documentation Index
> Fetch the complete documentation index at: https://docs.terratwin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Locations

> Define origins, destinations, and stopping points for TerraTwin transport calculations.

TerraTwin uses **locations** to decide where a shipment starts, where it ends, and where it stops along the way.

Every calculation needs an **origin** and a **destination**.
If you define a manual `transportChain`, every intermediate stopping point is represented as a `HUB` with its own `location`.
See the [logistics hubs guide](/content/guides/hubs) for modelling transfer activity and hub emissions at these stopping points.

<Columns cols={2}>
  <Card title="What a location identifies" icon="map-pin">
    A location can resolve to a general place, such as a building, street, postcode, city, or coordinates.
    It can also resolve to a transport facility, such as an airport, harbor, or rail yard.
  </Card>

  <Card title="Where locations appear" icon="route">
    Use locations in top-level `origin` and `destination` fields.
    Use the same location object inside `transportChain` hub elements for intermediate stops.
  </Card>
</Columns>

***

## Location types

Every location has a required `type`.
The `type` tells TerraTwin what kind of resolved point you want back.
It can be used with any supported way of identifying a location.

<Columns cols={2}>
  <Card title="PLACE" icon="map">
    Resolves to a general geographic point.
    Use this for addresses, cities, postcodes, buildings, or coordinates when you want the place itself.

    For air, water, or rail transport, TerraTwin can add first-mile or last-mile road connections from the place to a suitable airport, harbor or rail yard.
  </Card>

  <Card title="AIRPORT" icon="plane">
    Resolves to an airport.
    If `iataCode` is provided, that airport is used directly.
    Otherwise TerraTwin selects a nearby eligible airport from the supplied coordinates, address, city, postcode, or other reference point.
  </Card>

  <Card title="RAIL_YARD" icon="train">
    Resolves to a rail facility or rail network connection point.
    Rail yards are not identified by a dedicated code, so use coordinates or address information when you want a specific one.
  </Card>

  <Card title="HARBOR" icon="ship">
    Resolves to a maritime port.
    If `unLoCode` is provided, that harbor is used directly.
    Otherwise TerraTwin selects a nearby eligible harbor from the supplied coordinates, address, city, postcode, IATA airport code, or other reference point.
  </Card>
</Columns>

<Note>
  The identifier and the requested `type` do not need to match.

  When the identifier already points to the requested type, TerraTwin resolves that location directly. For example, an `iataCode` with `type: "AIRPORT"` identifies that airport.

  When the identifier points to a different type, TerraTwin treats it as a reference point and finds the closest suitable location of the requested `type`. For example, an `iataCode` with `type: "HARBOR"` finds the closest suitable harbor to that airport. A `unLoCode` with `type: "AIRPORT"` finds the closest suitable airport to that harbor.
</Note>

***

## Ways to define a location

TerraTwin accepts several location shapes. Choose the most precise information you have.

### Coordinates

Use decimal **WGS 84** coordinates: the same latitude and longitude format used by tools such as Google Maps.
Coordinates are sufficient by themselves to identify a location.

```json theme={null}
{
  "type": "PLACE",
  "latitude": 51.5033635,
  "longitude": -0.1276248
}
```

Coordinates can also be used to ask for a facility near that point.

```json theme={null}
{
  "type": "AIRPORT",
  "latitude": 51.5033635,
  "longitude": -0.1276248
}
```

***

### IATA airport code

Use a three-letter `iataCode` for airports.
An IATA code is sufficient by itself to identify an airport.
Codes are case-insensitive and normalized to uppercase.

```json theme={null}
{
  "type": "AIRPORT",
  "iataCode": "LHR"
}
```

***

### UN/LOCODE

Use `unLoCode` for locations represented by UN/LOCODE.
For harbors, a full five-character UN/LOCODE directly identifies the harbor.
Codes are case-insensitive and normalized to uppercase.

```json theme={null}
{
  "type": "HARBOR",
  "unLoCode": "GBSOU"
}
```

A three-letter location code can be used when paired with `countryCode`.
TerraTwin combines them into the full five-character code.

```json theme={null}
{
  "type": "HARBOR",
  "unLoCode": "SOU",
  "countryCode": "GB"
}
```

You can also use a UN/LOCODE as a reference point for another facility type.
This asks for a suitable airport near the UN/LOCODE location, not for the harbor itself.
If the air transport operation specifies an aircraft, TerraTwin uses that when selecting a compatible airport.

```json theme={null}
{
  "type": "AIRPORT",
  "unLoCode": "GBSOU"
}
```

Here, the closest suitable airport to Southampton harbor is, unsurprisingly, Southampton Airport.

***

### Structured address

Use structured address fields when you have them.
Structured addresses usually produce better matches than freeform addresses and are tolerant of minor data-entry issues.

A full structured address uses `street`, `postcode`, `city`, and `countryCode`.

```json theme={null}
{
  "type": "PLACE",
  "street": "10 Downing Street",
  "postcode": "SW1A 2AA",
  "city": "London",
  "countryCode": "GB"
}
```

Supplying the `region` can improve matching when other fields are missing or ambiguous.

```json theme={null}
{
  "type": "PLACE",
  "street": "Platz der Republik 1",
  "postcode": "11011",
  "city": "Berlin",
  "region": "Berlin",
  "countryCode": "DE"
}
```

<Note>
  `countryCode` accepts ISO 3166-1 alpha-2, alpha-3, and numeric country codes, such as `GB`, `GBR`, or `826`.
</Note>

***

### Partial structured address

When you do not have a full street address, TerraTwin can still geocode less precise locations.

For partial structured addresses, `countryCode` is always required. This applies whether you provide a street without a postcode, a postcode without a city, a city-only location, or any other incomplete combination of structured address fields.

```json theme={null}
{
  "type": "PLACE",
  "street": "Avenue Anatole France",
  "city": "Paris",
  "countryCode": "FR"
}
```

```json theme={null}
{
  "type": "PLACE",
  "street": "1600 Pennsylvania Ave NW",
  "postcode": "20500",
  "countryCode": "US"
}
```

```json theme={null}
{
  "type": "PLACE",
  "postcode": "90210",
  "countryCode": "US"
}
```

```json theme={null}
{
  "type": "PLACE",
  "city": "Rotterdam",
  "countryCode": "NL"
}
```

<Note>
  Postcode only and city only locations resolve to approximate area centroids. Providing coordinates or full address fields will give more accurate emissions calculation results.
</Note>

***

### Freeform address

Use `address` when the address is available as one unstructured string.

```json theme={null}
{
  "type": "PLACE",
  "address": "1600 Pennsylvania Avenue NW Washington DC 20500",
  "countryCode": "US"
}
```

<Warning>
  Address geocoding can be ambiguous, especially for freeform addresses. TerraTwin uses the highest confidence geocoding result when it meets the required certainty threshold. If no result meets that threshold, TerraTwin returns a geocoding error instead of guessing.
</Warning>

***

## Matching and selection behavior

When you provide a transport facility directly, TerraTwin uses that explicit facility.
For example, `type: "AIRPORT"` with `iataCode: "LHR"` uses Heathrow directly.
Likewise, `type: "HARBOR"` with `unLoCode: "GBSOU"` uses Southampton directly.

When you provide a reference point instead, TerraTwin selects an appropriate facility near that point.
That selection can consider operational constraints from the transport operation.

<Columns cols={2}>
  <Card title="Airport from freeform address" icon="plane">
    ```json theme={null}
    {
      "type": "AIRPORT",
      "address": "Amsterdam",
      "countryCode": "NL"
    }
    ```

    TerraTwin geocodes the address, then selects a suitable airport near the resolved point. In this case, it will be Amsterdam Airport Schiphol \[IATA:`AMS`].
  </Card>

  <Card title="Harbor from a partial structured address" icon="anchor">
    ```json theme={null}
    {
      "type": "HARBOR",
      "street": "Slottsplassen 1",
      "city": "Oslo",
      "countryCode": "NO"
    }
    ```

    TerraTwin geocodes the address, then selects a suitable harbor near the resolved point.
    In this case, the Port of Oslo \[`NOOSL`] will likely be selected.
  </Card>
</Columns>

Facility selection takes several factors into account:

* **Proximity to the supplied location** — closer facilities are generally preferred.
* **Customs-border crossings** — facilities that require crossing a customs border to reach are heavily penalized in the selection score.
* **Runway suitability** — airport selection considers whether the runways can accommodate the selected aircraft.
* **Harbor compatibility** — harbor selection considers the vessel type and capacity used by the associated `WATER` transport operation.
* **Rail network availability** — rail-yard selection considers whether the facility is connected to a suitable rail network.

Customs-border handling is especially important when the closest facility is in another country. TerraTwin may select a farther domestic facility over a closer international one if reaching the closer facility would require crossing a customs border.

For example, Plattsburgh, New York is closer to the Montreal container terminal \[`CAMTR`] than to any US container terminal. However, because using Montreal would require crossing the US-Canada customs border, TerraTwin will instead select the port of Portland \[`USPWM`].

<Frame caption="Portland [`USPWM`] chosen over Montreal [`CAMTR`] to avoid unnecessary border crossing">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/plattsburgh-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=da60469d7fe3ff34aef551b327fb16dc" width="918" height="605" data-path="images/locations/plattsburgh-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/plattsburgh-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=bccb6400bf3836b4dc09c7fb9c0d36da" width="918" height="605" data-path="images/locations/plattsburgh-dark.png" />
</Frame>

<Note>
  If you explicitly identify a facility, TerraTwin treats that as an override. For example, an explicitly supplied airport or harbor can be used even if it would not have been chosen automatically for the selected aircraft or vessel.
</Note>

***

## Multiple inputs on the same location

When several location properties are supplied together, TerraTwin resolves the location using a priority order that depends on the requested `type`.

| `type`      | Resolution priority                                                         |
| ----------- | --------------------------------------------------------------------------- |
| `PLACE`     | Coordinates → IATA code → structured address → freeform address → UN/LOCODE |
| `AIRPORT`   | IATA code → coordinates → structured address → freeform address → UN/LOCODE |
| `HARBOR`    | UN/LOCODE → coordinates → IATA code → structured address → freeform address |
| `RAIL_YARD` | Coordinates → IATA code → structured address → freeform address → UN/LOCODE |

<Note>
  Coordinates are the strongest signal for `PLACE`, but not for every location type. For example, an `AIRPORT` location with both `iataCode` and coordinates will resolve from the IATA code first, while a `HARBOR` location with both `unLoCode` and coordinates will resolve from the UN/LOCODE first.
</Note>

For `AIRPORT`, `HARBOR`, and `RAIL_YARD`, lower-priority inputs can still be useful as reference points when the highest-priority identifier is not supplied. For example, you can provide coordinates with `type: "HARBOR"` to ask TerraTwin to find the closest suitable harbor to those coordinates.

***

## Examples

### 1. Simple origin and destination

Use post code level `origin` and `destination` for the shipment endpoints.

```json theme={null}
{
  "cargo": {
    "weight": {
      "unit": "KILOGRAM",
      "value": 100
    }
  },
  "origin": {
    "type": "PLACE",
    "postcode": "SW1A 1AA",
    "countryCode": "GB"
  },
  "destination": {
    "type": "PLACE",
    "postcode": "1049",
    "countryCode": "BE"
  }
}
```

<Frame caption="Postcode SW1A 1AA London to postcode 1049 Belgium">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/london-to-belgium-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=ebfd0628865295e9160c68944f9b8017" width="987" height="325" data-path="images/locations/london-to-belgium-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/london-to-belgium-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=941dfe96ddd3d3dc57c03255557fcc9c" width="987" height="325" data-path="images/locations/london-to-belgium-dark.png" />
</Frame>

***

### 2. Airport to airport transport

Use IATA codes when you already know the airports.

```json theme={null}
{
  "cargo": {
    "weight": {
      "unit": "KILOGRAM",
      "value": 100
    }
  },
  "origin": {
    "type": "AIRPORT",
    "iataCode": "MAD"
  },
  "destination": {
    "type": "AIRPORT",
    "iataCode": "MIA"
  },
  "transportChain": [
    {
      "type": "AIR"
    }
  ]
}
```

<Frame caption="Madrid-Barajas [IATA:`MAD`] airport to Miami International Airport [IATA:`MIA`]">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/madrid-to-miami-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=9427e10fe83dd40a510d3581e7db207f" width="1022" height="344" data-path="images/locations/madrid-to-miami-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/madrid-to-miami-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=5df587f3beeaf1020937463c43be7343" width="1022" height="344" data-path="images/locations/madrid-to-miami-dark.png" />
</Frame>

***

### 3. Harbor to harbor

Use `type: "HARBOR"` when you want the route to start and/or end at maritime ports. A full UN/LOCODE is enough to identify each harbor directly.

```json theme={null}
{
  "cargo": {
    "weight": {
      "unit": "KILOGRAM",
      "value": 100
    }
  },
  "origin": {
    "type": "HARBOR",
    "unLoCode": "GBSOU"
  },
  "destination": {
    "type": "HARBOR",
    "unLoCode": "KEL",
    "countryCode": "DE"
  },
  "transportChain": [
    {
      "type": "WATER"
    }
  ]
}
```

<Tabs defaultTabIndex={1}>
  <Tab title="Southhampton harbor">
    <Frame caption="Port of Southhampton [`GBSOU`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/southhampton-harbor-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=10f8f558f0a2c609da93fc4bdc2510d5" width="814" height="505" data-path="images/locations/southhampton-harbor-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/southhampton-harbor-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=3f8845bd4a10875a892267f8107be5d9" width="814" height="505" data-path="images/locations/southhampton-harbor-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Southampton harbor to Kiel harbor">
    <Frame caption="Port of Southhampton [`GBSOU`] to Port of Kiel [`DEKEL`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/southhampton-to-kiel-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=d26fd7d8b0ad14ad2dff8daf496d8e9f" width="1189" height="635" data-path="images/locations/southhampton-to-kiel-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/southhampton-to-kiel-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=53ddc8d3d50031a5e47d5fbbfc1debc3" width="1189" height="635" data-path="images/locations/southhampton-to-kiel-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Kiel harbor">
    <Frame caption="Port of Kiel [`DEKEL`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/kiel-harbor-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=c81b2da54e3f074a67f8a93f71caabe5" width="1018" height="594" data-path="images/locations/kiel-harbor-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/kiel-harbor-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=893e6f9abd981fdc136d10d0ca172dde" width="1018" height="594" data-path="images/locations/kiel-harbor-dark.png" />
    </Frame>
  </Tab>
</Tabs>

***

### 4. Structured address to airport transport

This asks TerraTwin to start at an address and end at a specific airport.
For the air segment, TerraTwin will automatically add a first mile road connection from the address to the selected airport.

```json theme={null}
{
  "cargo": {
    "weight": {
      "unit": "KILOGRAM",
      "value": 100
    }
  },
  "origin": {
    "type": "PLACE",
    "street": "Calle de Bailén",
    "postcode": "28013",
    "city": "Madrid",
    "countryCode": "ES"
  },
  "destination": {
    "type": "AIRPORT",
    "iataCode": "FCO"
  },
  "transportChain": [
    {
      "type": "AIR"
    }
  ]
}
```

<Tabs defaultTabIndex={1}>
  <Tab title="Madrid First mile">
    <Frame caption="First mile road from Royal Palace of Madrid to Adolfo Suárez Madrid–Barajas Airport [IATA:`MAD`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/madrid-palace-to-barajas-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=c61d757aadc0de2a83e1861df52bba01" width="826" height="410" data-path="images/locations/madrid-palace-to-barajas-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/madrid-palace-to-barajas-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=7205c6905b98fb4e8a2bb41cacc19d8f" width="826" height="410" data-path="images/locations/madrid-palace-to-barajas-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Madrid Palace to Rome Fiumicino Airport">
    <Frame caption="Flight from Adolfo Suárez Madrid–Barajas Airport [IATA:`MAD`] to Rome Fiumicino Airport [IATA:`FCO`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/madrid-palace-to-fiumicino-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=ee1af1bff73fcc07a62137924aaa7054" width="829" height="289" data-path="images/locations/madrid-palace-to-fiumicino-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/madrid-palace-to-fiumicino-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=75acb5511513c8fe07f3028d9bd29f76" width="829" height="289" data-path="images/locations/madrid-palace-to-fiumicino-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Fiumicino Airport">
    <Frame caption="Rome Fiumicino Airport [IATA:`FCO`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/fiumicino-airport-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=a673b53f57ad52ff41650f2e7c8b86c7" width="776" height="561" data-path="images/locations/fiumicino-airport-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/fiumicino-airport-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=c00468a90719f8565e8ad4e46616426b" width="776" height="561" data-path="images/locations/fiumicino-airport-dark.png" />
    </Frame>
  </Tab>
</Tabs>

***

### 5. Free form addresses to identify places

Use freeform addresses when you have a human readable address instead of structured information. Always include `countryCode` so TerraTwin can geocode the address unambiguously.

```json theme={null}
{
  "cargo": {
    "weight": {
      "unit": "KILOGRAM",
      "value": 100
    }
  },
  "origin": {
    "type": "PLACE",
    "address": "3764 Elvis Presley Boulevard, Memphis, Tennessee",
    "countryCode": "US"
  },
  "destination": {
    "type": "PLACE",
    "address": "11 Wall Street, New York, NY 10005",
    "countryCode": "US"
  }
}
```

<Frame caption="Memphis, Tennessee to Wall Street, New York">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/memphis-to-new-york-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=2cb09fb7cf90b20e02429f6562f34951" width="869" height="419" data-path="images/locations/memphis-to-new-york-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/memphis-to-new-york-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=f8471f5834ee771769332fb0ddc9141d" width="869" height="419" data-path="images/locations/memphis-to-new-york-dark.png" />
</Frame>

***

### 6. Coordinate to coordinate

Use coordinates when you already know the exact origin and destination points. Coordinates are sufficient by themselves, so no address fields or country codes are needed.

```json theme={null}
{
  "cargo": {
    "weight": {
      "unit": "KILOGRAM",
      "value": 100
    }
  },
  "origin": {
    "type": "PLACE",
    "latitude": 51.503,
    "longitude": -0.127
  },
  "destination": {
    "type": "PLACE",
    "latitude": 50.941,
    "longitude": 6.958
  },
  "transportChain": [
    {
      "type": "ROAD"
    }
  ]
}
```

<Frame caption="51°30'10.80&#x22;N 00°07'37.20&#x22;W (**London**) to 50°56'27.60&#x22;N 06°57'28.80&#x22;E (**Cologne**)">
  <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/london-coordinates-to-cologne-coordinates-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=809c089a0c39ee0f5a76d23b97e7c60d" width="1429" height="432" data-path="images/locations/london-coordinates-to-cologne-coordinates-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/london-coordinates-to-cologne-coordinates-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=1093f0647cdd2bca5d5909d393567225" width="1429" height="432" data-path="images/locations/london-coordinates-to-cologne-coordinates-dark.png" />
</Frame>

***

### 7. Intermediate transfer point

Use a `HUB` element for intermediate transfer points in a `transportChain`.
The hub has its own `location` and can be a place, airport, rail yard, or harbor.

```json theme={null}
{
  "cargo": {
    "weight": {
      "unit": "KILOGRAM",
      "value": 100
    }
  },
  "origin": {
    "type": "PLACE",
    "street": "Amalienborg Slotsplads 5",
    "postcode": "1257",
    "city": "Copenhagen",
    "countryCode": "DK"
  },
  "destination": {
    "type": "PLACE",
    "address": "Therme București, Calea Bucureşti 1K, 077015 Balotești",
    "countryCode": "RO"
  },
  "transportChain": [
    {
      "type": "ROAD"
    },
    {
      "type": "HUB",
      "location": {
        "type": "HARBOR",
        "city": "Rotterdam",
        "countryCode": "NL"
      }
    },
    {
      "type": "WATER"
    }
  ]
}
```

<Tabs defaultTabIndex={1}>
  <Tab title="Rottendam transfer">
    <Frame caption="Port of Rotterdam [`NLRTM`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/copenhagen-rotterdam-transfer-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=913141da8126b43bc374b9be13a52219" width="994" height="650" data-path="images/locations/copenhagen-rotterdam-transfer-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/copenhagen-rotterdam-transfer-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=fffeb0722047e4ce20ab9c5dd6b575aa" width="994" height="650" data-path="images/locations/copenhagen-rotterdam-transfer-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Copenhagen to Bucharest">
    <Frame caption="Copenhagen to Bucharest">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/copenhagen-to-bucharest-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=f1affb2fe0f2978ec3d3e515a2da857d" width="1018" height="782" data-path="images/locations/copenhagen-to-bucharest-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/copenhagen-to-bucharest-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=f6a12dffd93ce7fcff2f2d42d5d403ee" width="1018" height="782" data-path="images/locations/copenhagen-to-bucharest-dark.png" />
    </Frame>
  </Tab>

  <Tab title="Constanța transfer">
    <Frame caption="Port of Constanța [`ROCND`]">
      <img className="block dark:hidden" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/constanta-transfer-light.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=0d555a2f5161a11bc4504975c78fa216" width="837" height="627" data-path="images/locations/constanta-transfer-light.png" />

      <img className="hidden dark:block" src="https://mintcdn.com/terratwin/0hbUXmLqgbSI5-VO/images/locations/constanta-transfer-dark.png?fit=max&auto=format&n=0hbUXmLqgbSI5-VO&q=85&s=2e6327c0efec305a84676b2086328209" width="837" height="627" data-path="images/locations/constanta-transfer-dark.png" />
    </Frame>
  </Tab>
</Tabs>

<Note>
  The example omits `hubType`.
  With automatic hub insertion enabled, TerraTwin selects a default from the surrounding `ROAD` to `WATER` transition.
  With `options.hubInsertion: "MANUAL"`, the hub remains a location boundary but does not contribute hub emissions.
  See [How a hub type is selected](/content/guides/hubs#how-a-hub-type-is-selected).
</Note>

***

## Recommendations

<Steps>
  <Step title="Always provide a location type">
    Include `type` on every `origin`, `destination`, and hub `location`. Use `PLACE` for general geographic points, or `AIRPORT`, `HARBOR`, and `RAIL_YARD` when you want TerraTwin to resolve a specific facility type.
  </Step>

  <Step title="Use the most precise identifier you have">
    Prefer coordinates for exact places, `iataCode` for known airports, `unLoCode` for known harbors, and structured address fields when address components are available.
  </Step>

  <Step title="Include country codes for addresses">
    Provide `countryCode` with structured, partial structured, and freeform addresses. Also include it when using a three-letter `unLoCode` so TerraTwin can construct the full five character code.
  </Step>

  <Step title="Be explicit when you want a facility">
    Use `AIRPORT`, `HARBOR`, or `RAIL_YARD` when the route should pass through a transport facility. Use `PLACE` when you want the shipment endpoint itself and TerraTwin will add first-mile or last-mile connections as needed.
  </Step>

  <Step title="Use hubs for known transfer points">
    Add intermediate stops as `HUB` elements in `transportChain`, and give each hub its own `location`. This is the right way to force a specific airport, harbor, rail yard, or transfer place into the route.
  </Step>
</Steps>

***

## Common mistakes

* Omitting `type` from a location.
* Using `address` or structured address fields without `countryCode`.
* Sending degrees/minutes/seconds instead of decimal WGS 84 coordinates.
* Using a three-letter `unLoCode` without `countryCode`.
* Expecting `type: "PLACE"` to select an airport, harbor, or rail yard. Use `AIRPORT`, `HARBOR`, or `RAIL_YARD` when you want a facility.