# Shipper Facilities 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"`. Must be sent together with `state` and must geocode successfully; unrecognized locations return empty. * **`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"`. Must be sent together with `city` and must geocode successfully; unrecognized locations return empty. * **`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`. The match is case-insensitive and anchored on the host substring, so `acme.com` will match stored URLs like `https://www.acme.com/contact`, `http://shipping.acme.com`, and `acme.com.au`. Minimum accepted form is `a.com` (must contain a `.` and a 2+ character TLD). Shorter inputs return HTTP 400. * **`radius`** *(number, optional, default `20`, max `150`)* The radius in miles within which to search around the specified location. Only takes effect when paired with a successful `city` + `state` geocode — sent alone, it has no effect. * **`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`. To pass multiple values, separate them with a pipe — e.g. `Small | Medium`. * **`zip_code`** *(string, optional, max 10 chars)* Search for facilities by valid US zip code. Can be combined with other search parameters like **`name`** or **`address`** to further narrow results. * **`include_lanes`** *(string, optional)* Accepts only *true*, each facility in the response includes inbound\_lanes and outbound\_lanes arrays containing structured freight lane data ranked by weight. Facilities with no matching lane data are excluded from the response. Enables pagination — see *cursor* below. * **`top_n`** *(number, optional, default 10, max 50)* The number of top lanes to return per direction (inbound/outbound) per facility, ranked by weight descending. For example, top\_n=5 returns the 5 highest-weighted inbound and 5 highest-weighted outbound lanes. Only takes effect when **`include_lanes`**=true. * **`min_distance`** *(number, optional, miles)* Minimum distance in miles from the facility to a lane destination. Lanes closer than this threshold are excluded. For example, min\_distance=200 returns only lanes where the destination is 200+ miles away. Applied before **`top_n`**. Only takes effect when **`include_lanes`**=true. * **`direction`** *(string, optional, one of: N, S, E, W, NE, NW, SE, SW)* Filter lanes by compass direction from the facility. For example, **`direction`**=NE returns only lanes heading northeast. Applied before **`top_n`**. Only takes effect when **`include_lanes`**=true. * **`limit`** *(number, optional)* Filter lanes by compass direction from the facility. For example, **`direction`**=NE returns only lanes heading northeast. Applied before **`top_n`**. Only takes effect when **`include_lanes`**=true. * **`cursor`** *(string, optional, opaque)* Pagination cursor from the Link response header of a previous request. Do not construct, parse, or cache this value — follow the URL provided in the Link header. Only present in responses when **`include_lanes`**=true and results exceed 20 facilities. ### **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`. ```sh 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` ```shellscript 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` ```shellscript curl -X GET 'https://api.genlogs.io/facilities?zip_code=12345' \ -H 'Access-Token: {access_token}' \ -H 'x-api-key: {your_api_key}' \ ``` ## Search facilities by name, address, zip code, city/state, website domain, or coordinates > Unified facility search. Provide at least one of: non-empty **`name`**, non-empty **`address`**, **`zip_code`**, non-empty **`website_domain`**, or both **`city`** and **`state`** (then use **`radius`** around the geocoded point). You may also pass **`location`** as `latitude,longitude` for radius search instead of city/state.