Locations - TerraTwin API Documentation

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 for modelling transfer activity and hub emissions at these stopping points.

What a location identifies

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.

Where locations appear

Use locations in top-level origin and destination fields. Use the same location object inside transportChain hub elements for intermediate stops.

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.

PLACE

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.

AIRPORT

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.

RAIL_YARD

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.

HARBOR

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.

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.

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.

{
  "type": "PLACE",
  "latitude": 51.5033635,
  "longitude": -0.1276248
}

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

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "type": "PLACE",
  "street": "Platz der Republik 1",
  "postcode": "11011",
  "city": "Berlin",
  "region": "Berlin",
  "countryCode": "DE"
}

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

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.

{
  "type": "PLACE",
  "street": "Avenue Anatole France",
  "city": "Paris",
  "countryCode": "FR"
}

{
  "type": "PLACE",
  "street": "1600 Pennsylvania Ave NW",
  "postcode": "20500",
  "countryCode": "US"
}

{
  "type": "PLACE",
  "postcode": "90210",
  "countryCode": "US"
}

{
  "type": "PLACE",
  "city": "Rotterdam",
  "countryCode": "NL"
}

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

Freeform address

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

{
  "type": "PLACE",
  "address": "1600 Pennsylvania Avenue NW Washington DC 20500",
  "countryCode": "US"
}

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.

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.

Airport from freeform address

{
  "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].

Harbor from a partial structured address

{
  "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.

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].

Portland [`USPWM`] chosen over Montreal [`CAMTR`] to avoid unnecessary border crossing

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.

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

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.

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.

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

Postcode SW1A 1AA London to postcode 1049 Belgium

2. Airport to airport transport

Use IATA codes when you already know the airports.

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

Madrid-Barajas [IATA:`MAD`] airport to Miami International Airport [IATA:`MIA`]

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.

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

Southhampton harbor
Southampton harbor to Kiel harbor
Kiel harbor

Port of Southhampton [`GBSOU`] to Port of Kiel [`DEKEL`]

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.

{
  "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"
    }
  ]
}

Madrid First mile
Madrid Palace to Rome Fiumicino Airport
Fiumicino Airport

First mile road from Royal Palace of Madrid to Adolfo Suárez Madrid–Barajas Airport [IATA:`MAD`]

Flight from Adolfo Suárez Madrid–Barajas Airport [IATA:`MAD`] to Rome Fiumicino Airport [IATA:`FCO`]

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.

{
  "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"
  }
}

Memphis, Tennessee to Wall Street, New York

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.

{
  "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"
    }
  ]
}

51°30'10.80"N 00°07'37.20"W (London) to 50°56'27.60"N 06°57'28.80"E (Cologne)

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.

{
  "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"
    }
  ]
}

Rottendam transfer
Copenhagen to Bucharest
Constanța transfer

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.

Recommendations

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.

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.

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.

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.

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.

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.

What a location identifies

Where locations appear

​Location types

PLACE

AIRPORT

RAIL_YARD

HARBOR

​Ways to define a location

​Coordinates

​IATA airport code

​UN/LOCODE

​Structured address

​Partial structured address

​Freeform address

​Matching and selection behavior

Airport from freeform address

Harbor from a partial structured address

​Multiple inputs on the same location

​Examples

​1. Simple origin and destination

​2. Airport to airport transport

​3. Harbor to harbor

​4. Structured address to airport transport

​5. Free form addresses to identify places

​6. Coordinate to coordinate

​7. Intermediate transfer point

​Recommendations

​Common mistakes

Location types

Ways to define a location

Coordinates

IATA airport code

UN/LOCODE

Structured address

Partial structured address

Freeform address

Matching and selection behavior

Multiple inputs on the same location

Examples

1. Simple origin and destination

2. Airport to airport transport

3. Harbor to harbor

4. Structured address to airport transport

5. Free form addresses to identify places

6. Coordinate to coordinate

7. Intermediate transfer point

Recommendations

Common mistakes