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.

website_domain vs. contact_url in the response. website_domain is an input filter — the value you send to narrow the search. contact_url is the output field on each facility record and holds the full URL as Genlogs ingested it (scheme, subdomain, path, and all). The filter is a substring match against contact_url, so the two will usually look related but rarely identical: you filter by acme.com and get back facilities whose contact_url is https://www.acme.com/locations/12. Do not expect contact_url to echo the domain you sent.

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. Matching is case-insensitive.

Filter precedence. name, address, and website_domain are mutually exclusive text filters. If you send more than one, only the highest-priority filter is applied (name > address > website_domain) — the others are silently ignored.

Geographic narrowing is layered on top of whichever text filter wins:

city + state must both be sent and must geocode successfully; unrecognized locations are dropped silently and return ungeoed results.
radius (miles) only takes effect when paired with a successful city + state geocode. Sent alone, it has no effect.

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.

Lane Data Behavior. When include_lanes=true is sent, the response changes in several ways:

Each facility includes inbound_lanes and outbound_lanes arrays ranked by weight
Facilities with no matching lane data are excluded from the response
Results are paginated at 20 facilities per page — check the Link response header for the next page URL
The limit parameter is capped at 20 regardless of the value provided
Lane-specific filters (top_n, min_distance, direction) only take effect in this mode
Without include_lanes=true, none of the above applies — the response contains facility metadata only, no pagination headers, and limit follows the standard defaults.

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.

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

Search facilities by name, address, zip code, city/state, website domain, or coordinates

get

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. Optionally include lane data per facility with include_lanes=true. Lanes can be filtered by min_distance (miles from facility) and direction (compass direction). Filters are applied before the top_n limit.

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. The X-Total-Count header shows the total matching facilities across all pages. Pagination is not supported with smart_search=true. See component schema FacilitiesQueryCriteria for the full parameter model and validation shape. Historical path /find_facilities exposes the same search behavior and is documented here as /facilities for a single contract.

Query parameters

namestring · max: 500Optional

Facility or collection name (optional if address, both city and state, or website_domain are provided). See FacilitiesQueryCriteria for validation rules.

Example: Example Warehouse

addressstring · max: 500Optional

Substring match on formatted address (optional if name, both city and state, or website_domain are provided).

Example: 123 Main St, Dallas, TX

citystring · max: 150Optional

City; use with state for geocoded radius search unless name, address, or website_domain alone is sufficient.

Example: Dallas

statestring · max: 150Optional

State; use with city unless name, address, or website_domain supplies the search mode.

Example: TX

website_domainstring · min: 5 · max: 253Optional

Substring match against the shipper's contact_url. Must include the TLD (e.g. acme.com). Optional path tails (acme.com/about) are accepted by the validator but the path is stripped before matching — only the host is searched.

Mutually exclusive with name and address. If name or address is also supplied, website_domain is silently ignored (see FacilitiesQueryCriteria → Filter precedence). Also ignored when smart_search=true is used together with name.

Example: genlogs.ioPattern: ^[A-Za-z0-9][A-Za-z0-9-]*\.[A-Za-z]{2,}([/.].*)?$

locationstringOptional

Comma-separated latitude,longitude; radius applies around this point when provided instead of city/state.

Example: 32.7767,-96.7970

radiusnumber · max: 150Optional

Search radius in miles around the geocoded city/state point or location

Example: 50

lot_size_categorystring · max: 50Optional

Lot size category filter

Example: large

limitintegerOptional

Maximum number of facilities to return

Example: 100

facility_typestring · max: 500Optional

Optional place category filter (pipe-separated values accepted by the service)

intermodal_drayagestringOptional

Optional intermodal drayage filter flag

Example: false

include_lanesbooleanOptional

Include inbound and outbound lane data for each facility. Lanes are ranked by weight.

Example: true

top_nintegerOptional

Number of top lanes to return per direction (inbound/outbound) per facility.

Default: 10Example: 5

min_distancenumberOptional

Minimum distance in miles from the facility to a lane destination. Lanes closer than this distance are excluded. Applied before top_n.

Example: 200

directionstring · enumOptional

Filter lanes by compass direction from the facility. Applied before top_n.

Example: NEPossible values:

zip_codestringOptional

US zip code; searches facilities near the zip centroid.

Example: 75207

cursorstring · max: 500Optional

Opaque pagination cursor from the Link header of a previous response. When results exceed 100 facilities, the server returns a Link header containing a next-page URL with this cursor embedded. Follow that URL to retrieve subsequent pages. Do not construct or parse this value — it is server-controlled and opaque.

Header parameters

acceptstringRequired

application/json

Example: application/json

Access-TokenstringRequired

Access Token for authentication

Example: [Token]

x-api-keystringRequired

X api key for authentication

Example: [x-api-key]

Responses

200

List of facilities

application/json

400

Validation error (missing search criteria, invalid parameters, or invalid cursor)

get/facilities

GET /facilities HTTP/1.1
Host: api.genlogs.io
accept: application/json
Access-Token: [Token]
x-api-key: [x-api-key]
Accept: */*

[
  {
    "contact_phone": "text",
    "contact_url": "text",
    "facility_name": "text",
    "formatted_address": "text",
    "id": "text",
    "lat": 1,
    "lon": 1,
    "operating_hours": "text",
    "place_category": "text",
    "equipment_pairings": [
      "Dry Van",
      "Box Truck"
    ],
    "inbound_lanes": [
      {
        "city": "text",
        "state": "text",
        "weight": 1,
        "visit_share": "text",
        "hexagon_id": "text",
        "distance_miles": 1,
        "direction": "text"
      }
    ],
    "outbound_lanes": [
      {
        "city": "text",
        "state": "text",
        "weight": 1,
        "visit_share": "text",
        "hexagon_id": "text",
        "distance_miles": 1,
        "direction": "text"
      }
    ]
  }
]

PreviousShipper Lanes

NextFacility Network Map

Last updated 3 months ago