Shipper Facilities | Genlogs API Docs

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.

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

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

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.