On this page

The facilities endpoint allows users to retrieve a list of facilities that match a given name, location, and search radius. The response includes detailed information about each facility, such as contact information, geographic coordinates, and operating hours.

### Authentication

Include the following headers in your requests:

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

### Permissions

Make sure that your api user is created with a role that has `external-api-shipper-facilities` permission.

### Endpoint

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

### Query Parameters

- `name` _(string, max 500 chars, required — only optional when `address`, `website_domain`, or a `city` + `state` combination is provided)_ The name of the facility to search for. For example, "Acme Logistics".
- `address` _(string, max 500 chars, required — only optional when `name`, `website_domain`, or a `city` + `state` combination is provided)_ The address of the facility to search for. For example, "123 Main Street South".
- `city` _(string, max 150 chars, required — only optional when `name`, `address`, or `website_domain` is provided)_ The location "city" around which to search for facilities. For example, "Boston" or "Atlanta".
- `state` _(string, max 150 chars, required — only optional when `name`, `address`, or `website_domain` is provided)_ The location "state" around which to search for facilities. For example, "Massachusetts" or "Georgia".
- `website_domain` _(string, optional, max 253 chars)_ Returns facilities whose stored contact URL contains the given domain. Provide the bare host only — e.g. `acme.com`, not `https://www.acme.com/about`.
- `radius` _(number, optional, default `20`, max `150`)_ The radius in miles within which to search around the specified location.
- `lot_size_category` _(string, optional, max 50 chars)_ Filter by the lot size category of the facility. Accepts one or more of `Small`, `Medium`, `Large`, `X-Large`.
- `zip_code` _(string, optional, max 10 chars)_ Search for facilities by valid US zip code.
- `include_lanes` _(string, optional)_ Accepts only _true_, each facility in the response includes inbound_lanes and outbound_lanes arrays containing structured freight lane data.
- `top_n` _(number, optional, default 10, max 50)_ The number of top lanes to return per direction (inbound/outbound) per facility.
- `min_distance` _(number, optional, miles)_ Minimum distance in miles from the facility to a lane destination.
- `direction` _(string, optional, one of: N, S, E, W, NE, NW, SE, SW)_ Filter lanes by compass direction from the facility.
- `cursor` _(string, optional, opaque)_ Pagination cursor from the Link response header of a previous request.

### Response

- **200 OK**: Successfully retrieved the list of facilities matching the search criteria.
- **400 Bad Request**: If required parameters are missing or invalid.
- **401 Unauthorized**: If the `Access-Token` or `x-api-key` is missing or invalid.
- **500 Internal Server Error**: If an error occurs on the server while processing the request.

### Response Body

- **facilities** (array of `Facility` objects): List of up to 1,000 facilities matching the search criteria ordered by relative load volume.
  - **contact_phone** (nullable string): Phone number of the facility's contact person.
  - **contact_url** (nullable string): URL for the facility's contact page or website.
  - **facility_name** (string): Name of the facility.
  - **formatted_address** (string): Full address of the facility.
  - **id** (string): Unique identifier for the facility.
  - **inbound_lanes** (array): Lanes inbound to a facility, ranked by weight descending.
  - **lat** (number): Latitude of the facility's location.
  - **lon** (number): Longitude of the facility's location.
  - **operating_hours** (nullable string): Operating hours of the facility.
  - **outbound_lanes** (array): Lanes outbound from a facility, ranked by weight descending.
  - **place_category** (string): Category or type of place (e.g., warehouse, distribution center).
  - **place_desc**(String): Description of the facility.
  - **equipment_pairings** (List): Equipment types paired with this facility based on observed carrier activity.

### Request Example:

Search by `name` + `city` and `state`.
```bash
curl -X GET 'https://api.genlogs.io/facilities?name=coca+cola&city=&state=&radius=50' \
-H 'Access-Token: {access_token}' \
-H 'x-api-key: {your_api_key}' 
```

Search by `address`
```bash
curl -X GET 'https://api.genlogs.io/facilities?address=123%20Main%20Street%20South' \
-H 'Access-Token: {access_token}' \
-H 'x-api-key: {your_api_key}' 
```

Search by `zip_code`
```bash
curl -X GET 'https://api.genlogs.io/facilities?zip_code=12345' \
-H 'Access-Token: {access_token}' \
-H 'x-api-key: {your_api_key}' 
```

### Pagination

When results exceed 100 facilities, the response is paginated using opaque cursor-based pagination. The `Link` response header contains a next-page URL with a `cursor` parameter. Follow that URL to retrieve subsequent pages.