# GenLogs' Real-Time API

With GenLogs' Real-Time API, you can instantly identify carriers with the right equipment who are currently within a 150-mile radius of your origin and are likely seeking backhauls to your destination. Integrate Real-Time GenLogs data into your TMS and internal systems to unlock new opportunities, increase efficiency, and reduce empty miles.

When the `real_time` parameter is set to 'True', the recommendation system prioritizes real-time data by applying additional weight to recent detections near the origin of the search. While the recommendations still incorporate historical data and follow the usual logic, the real-time information takes precedence, resulting in a more dynamic focus on current activity.

## Permissions

The `realtime-api` permission is required to use this parameter.

The `real_time` parameter is available exclusively to premium users. Reach out to us at [support@genlogs.io](mailto:support@genlogs.io) now to unlock Real-Time freight data.

## Endpoint

- **URL:** `https://api.genlogs.io/carrier/recommendations`
- **Method:** `GET`

## Headers

- **Access-Token**: `token` (string, required): The access token obtained from the "Create Access Token" endpoint.
- **x-api-key** (string, required): The API key provided by GenLogs. This header must be included in the request

## Query Parameters

Use the `real_time` parameter in addition to the required and optional base parameters described in the [Carrier Recommendations](https://docs.genlogs.io/carrier/recommendations#query-parametersreal_time) document.

1. **real_time** (boolean, optional): Indicates whether to return recommendations that include real-time detections. If enabled, carriers recently seen within 150-mi of your search radius will be returned.

*Tip: A 403 error received while using the `real_time` parameter signifies that your user account lacks access to this premium feature. To resolve this, please verify your access level. If you require further assistance, don't hesitate to contact our support team at [support@genlogs.io](mailto:support@genlogs.io).*

## Response Body

1. **real_time_locs** (dictionary of locations where real time carrier observations)
   - **dot_number**: string, usdot of the detected carrier.
   - **current_lon**: float, longitude of the detection location.
   - **current_lat**: float, latitude of the detection location.
   - **is_inbound** (bool): flag indicates when a carrier is currently inbound to the origin.

2. **recommendations** (array of `CarrierRecommendation` objects): List of recommended carriers.

3. `is_inbound` appears in: [1] `real_time_locs[is_inbound]`, [2] `rt_detection_detail[][][is_inbound]` – both mean carrier inbound to origin.

## Request Example

```bash
curl -X GET 'https://api.genlogs.io/carrier/recommendations?origin_city=Tucker&origin_state=Georgia&destination_city=Orange+Park&destination_state=Florida&origin_radius=50.0&destination_radius=50.0&fleet_size_min=0&fleet_size_max=1000&preferred_carriers=True&real_time=True' \  
-H 'Access-Token: {access_token}' \  
-H 'x-api-key: {your_api_key}' \  
-i
```

## Get carrier recommendations based on location

**GET `https://api.genlogs.io/carrier/recommendations`**

### Query parameters

- **origin_city** string **Required** - Origin city for the recommendation (Default: `Nashville`). Example: `Tennessee City`
- **origin_state** string **Required** - Origin state for the recommendation (Default: `TN`). Example: `Tennessee`
- **destination_city** string **Required** - Destination city for the recommendation (Default: `Dallas`). Example: `Tascosa`
- **destination_state** string **Required** - Destination state for the recommendation (Default: `TX`). Example: `Texas`
- **origin_radius** number **Optional** - Search radius around the origin location in miles (Default: `50`). Example: `50`
- **destination_radius** number **Optional** - Search radius around the destination location in miles (Default: `50`). Example: `50`
- **carrier_score_min** number **Optional** - Minimum carrier score (Default: `0`). Example: `0`
- **carrier_score_max** number **Optional** - Maximum carrier score (Default: `100`). Example: `100`
- **fleet_size_min** number **Optional** - Minimum fleet size (Default: `1`). Example: `1`
- **fleet_size_max** number **Optional** - Maximum fleet size (Default: `500`). Example: `500`
- **carried_cargo** string **Optional** - Type of cargo carried (Default: `general goods`). Example: `general goods`
- **equipment_types** string **Optional** - Type of equipment used by carriers (Default: `flatbed`). Example: `flatbed`
- **preferred_carriers** boolean **Optional** - Filter for preferred carriers (Default: `false`). Example: `true`
- **real_time** boolean **Optional** - Request real-time data if available (Default: `false`). Example: `true`
- **auth_months_min** number **Optional** - Minimum number of months a carrier has an active common or contract authority with FMCSA (Default: `1`). Example: `1`

### Header parameters

- **accept** string **Required** - Specifies the format of the response (Default: `application/json`). Example: `application/json`
- **Access-Token** string **Required** - Access Token for authentication. Example: `[Token]`
- **x-api-key** string **Required** - API key for authentication. Example: `[x-api-key]`

### Responses

**200**  
The JSON response containing recommendations and lane volume.

```json
{
  "real_time_locs": [
    {
      "current_lat": 1,
      "current_lon": 1,
      "dot_number": "text",
      "is_inbound": true
    }
  ],
  "recommendations": [
    {
      "add_date": "text",
      "bipd_insurance_on_file": 1,
      "cargo_insurance_on_file": 1,
      "carried_cargo": "text",
      "carrier_driver_oos_rate": 1,
      "carrier_driver_oos_rate_national_avg": 1,
      "carrier_score_scaled": 1,
      "carrier_total_power_units": 1,
      "carrier_vehicle_oos_rate": 1,
      "carrier_vehicle_oos_rate_national_avg": 1,
      "dba_name": "text",
      "dot_number": "text",
      "email_address": "text",
      "is_inbound": true,
      "is_real_time": true,
      "is_visually_sighted": true,
      "is_possible_backhaul": true,
      "lat": 1,
      "legal_name": "text",
      "lon": 1,
      "mc_number": 1,
      "phy_city": "text",
      "phy_state": "text",
      "phy_street": "text",
      "phy_zip": "text",
      "telephone": "text"
    }
  ]
}
```

_Last updated 3 months ago_