# 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, Required (Only optional when address or city and state combination is provided)): The name of the facility to search for.
* **address** (string, Required (Only optional when name or city and state combination is provided)): The address of the facility to search for. For example "123 Main Street South".
* **city** (string, Required (Only optional when name or address is provided)): The location "city" around which to search for facilities. For example, "Boston" or "Atlanta".
* **state** (string, Required (Only optional when name or address is provided)): The location "state" around which to search for facilities. For example, "Massachusetts" or "Georgia".
* **radius** (integer, Optional \[Default: 20]): The radius (in miles) within which to search around the specified location.
* **lot\_size\_category** (string, Optional): The size of lot category, if you want to use different ones remember to use | between them, for example `Small | Medium` .
  * List of lot size category

    ```
    Small
    Medium
    Large
    X-Large
    ```

### **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.
  * **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.
  * **place\_category** (string): Category or type of place (e.g., warehouse, distribution center).

### 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}' \
```

## GET /facilities

> Get facilities based on name, location, and radius

```json
{"openapi":"3.0.2","info":{"title":"Shipper API","version":"1.0.0"},"servers":[{"url":"https://api.genlogs.io"}],"paths":{"/facilities":{"get":{"parameters":[{"name":"accept","in":"header","required":true,"schema":{"type":"string"},"description":"application/json"},{"name":"Access-Token","in":"header","required":true,"schema":{"type":"string"},"description":"Access Token for authentication"},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"X api key for authentication"},{"description":"The name of the facility","in":"query","name":"name","required":true,"schema":{"type":"string"}},{"description":"The city of the facility","in":"query","name":"city","required":true,"schema":{"type":"string"}},{"description":"The state of the facility","in":"query","name":"state","required":true,"schema":{"type":"string"}},{"description":"The radius to search around the location","in":"query","name":"radius","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacilityResponse"}}},"description":"List of facilities"}},"summary":"Get facilities based on name, location, and radius"}}},"components":{"schemas":{"FacilityResponse":{"properties":{"facilities":{"items":{"$ref":"#/components/schemas/Facility"},"type":"array"}},"required":["facilities"],"type":"object"},"Facility":{"properties":{"contact_phone":{"nullable":true,"type":"string"},"contact_url":{"nullable":true,"type":"string"},"facility_name":{"type":"string"},"formatted_address":{"type":"string"},"id":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"operating_hours":{"nullable":true,"type":"string"},"place_category":{"type":"string"}},"required":["facility_name","formatted_address","id","lat","lon","place_category"],"type":"object"}}}}
```