/geodata/getdistance - Get distance between locations

Overview

The /geodata/getdistance endpoint calculates the driving distance and travel time between two locations using the Google Distance Matrix API.

Purpose

• Get accurate driving distances between locations
• Calculate estimated travel time
• Support trip planning with real road distances
• Provide routing information for resort accessibility
• Enable "how far is this resort" functionality

Endpoint

GET /geodata/getdistance

Parameters

Query parameters

origin (string, required)

Starting location for the distance calculation.

Formats:

• Address string: "Oslo, Norway"
• Place name: "Trysil"
• Latitude,Longitude: "59.9139,10.7522"
• Place ID: "ChIJ0WGkg4FgQUYRlbYCkXvP1Zk" (Google Places ID)

Examples:

• origin=Oslo, Norway - From Oslo city
• origin=59.9139,10.7522 - From coordinates
• origin=Bergen Sentrum - From Bergen center

Note: The value is geocoded by Google's API, so natural language addresses work well.

---

destination (string, required)

Destination location for the distance calculation.

Formats: Same as origin parameter

• Address string
• Place name
• Latitude,Longitude coordinates
• Place ID

Examples:

• destination=Trysil, Norway - To Trysil
• destination=61.3150,12.2680 - To coordinates
• destination=Hemsedal Skisenter - To Hemsedal resort

---

Response format

Success response structure

{
  "origin_addresses": ["Oslo, Norway"],
  "destination_addresses": ["Trysil, Norway"],
  "rows": [
    {
      "elements": [
        {
          "distance": {
            "text": "231 km",
            "value": 231000
          },
          "duration": {
            "text": "2 hours 45 mins",
            "value": 9900
          },
          "status": "OK"
        }
      ]
    }
  ],
  "status": "OK"
}

Response with multiple destinations

{
  "origin_addresses": ["Oslo, Norway"],
  "destination_addresses": [
    "Trysil, Norway",
    "Hemsedal, Norway"
  ],
  "rows": [
    {
      "elements": [
        {
          "distance": {
            "text": "231 km",
            "value": 231000
          },
          "duration": {
            "text": "2 hours 45 mins",
            "value": 9900
          },
          "status": "OK"
        },
        {
          "distance": {
            "text": "198 km",
            "value": 198000
          },
          "duration": {
            "text": "2 hours 30 mins",
            "value": 9000
          },
          "status": "OK"
        }
      ]
    }
  ],
  "status": "OK"
}

Error response (missing parameters)

{
  "error": "you need to specify origin and destination"
}

HTTP Status: 400

### Error response (API error)

---

## Response fields

### Top level fields

- **`origin_addresses`** (array): Geocoded origin addresses as formatted by Google
  - Each string is a formatted address (e.g., "Oslo, Norway")

- **`destination_addresses`** (array): Geocoded destination addresses
  - Each string is a formatted address

- **`rows`** (array): Matrix of results (one row per origin)
  - Each row contains an `elements` array with results for each destination

- **`status`** (string): Overall API request status
  - `"OK"` - Successful request
  - `"INVALID_REQUEST"` - Invalid request parameters
  - `"MAX_ELEMENTS_EXCEEDED"` - Too many elements requested
  - `"OVER_DAILY_LIMIT"` - API quota exceeded
  - `"OVER_QUERY_LIMIT"` - Too many requests
  - `"REQUEST_DENIED"` - API key issue
  - `"UNKNOWN_ERROR"` - Server error

### Element Fields (rows[].elements[])

Each element in the distance matrix contains:

- **`distance`** (object): Distance information
  - `text` (string): Human-readable distance (e.g., "231 km")
  - `value` (integer): Distance in meters (e.g., 231000)

- **`duration`** (object): Travel time information
  - `text` (string): Human-readable duration (e.g., "2 hours 45 mins")
  - `value` (integer): Duration in seconds (e.g., 9900)

- **`status`** (string): Status for this specific origin-destination pair
  - `"OK"` - Route found successfully
  - `"NOT_FOUND"` - Origin or destination not found
  - `"ZERO_RESULTS"` - No route found between locations
  - `"MAX_ROUTE_LENGTH_EXCEEDED"` - Route too long

---

## Example requests

### Simple distance calculation

GET /geodata/getdistance?origin=Oslo,Norway&destination=Trysil,Norway

Calculates driving distance and time from Oslo to Trysil.

---

### Distance from coordinates

GET /geodata/getdistance?origin=59.9139,10.7522&destination=61.3150,12.2680

Calculates distance from Oslo coordinates to Trysil coordinates.

---

### Distance to resort

GET /geodata/getdistance?origin=Bergen&destination=Voss+Resort

Calculates distance from Bergen to Voss Resort.

---

### Multiple destinations

GET /geodata/getdistance?origin=Oslo&destination=Trysil|Hemsedal|Geilo

Calculates distances from Oslo to multiple ski resorts (pipe-separated destinations).

---

## Distance matrix details

### How it works

1. **Geocoding**: Both origin and destination are geocoded to coordinates
2. **Routing**: Google calculates the optimal driving route
3. **Distance**: Total driving distance along the route
4. **Duration**: Estimated travel time considering typical traffic patterns

- Results come directly from Google Distance Matrix API

### Supported locations

- City names (e.g., "Oslo")
- Full addresses (e.g., "Storgata 1, Oslo")
- Landmark names (e.g., "Oslo Airport")
- Coordinates (e.g., "59.9139,10.7522")
- Postal codes (e.g., "0150 Oslo")

### Multiple Origins/Destinations

The API supports multiple origins and/or destinations by using pipe (`|`) separator:

origin=Oslo|Bergen&destination=Trysil|Hemsedal

This creates a 2x2 matrix with 4 distance calculations.

---

## Use Cases

1. **Trip planning**: Calculate driving time to a resort from user's location
2. **Resort comparison**: Compare distances from a city to multiple resorts
3. **Accessibility information**: Show how far a resort is from major cities
4. **Travel time estimates**: Display estimated travel duration on resort pages
5. **Route optimization**: Find the closest resort by driving distance (not straight-line)
6. **Mobile apps**: "How do I get there" functionality
7. **Carpool coordination**: Calculate distances between user locations and resorts

---

## Notes

- Both `origin` and `destination` parameters are **required**
- Missing either parameter returns a 400 error
- Uses **Google Distance Matrix API** for accurate driving distances
- Results include **real road distances**, not straight-line distances
- Travel duration considers **typical traffic patterns** (not real-time traffic)
- Supports **multiple modes of transport** (driving is default)
- Geocoding is **automatic** - natural language addresses work well
- **API quotas** apply - excessive usage may result in quota errors
- The endpoint includes **retry logic** for transient API failures (5xx, 408, 429 errors)
- Distances are returned in **metric units** (kilometers, meters)
- Duration is returned in **seconds** (value) and human-readable format (text)
- For straight-line distances, use `/geodata/getnearest` instead
- For international routes, ensure proper country formatting (e.g., "Oslo, Norway")
- The service may return `ZERO_RESULTS` if no route exists (e.g., islands without ferry service)
- Coordinates should use **decimal degrees** format with comma separator (no spaces)
- URL-encode addresses with special characters or spaces (e.g., `Oslo%20Airport`)