Querying Facilities

The facility list tells you which SpotHero locations your account can access. Each facility has a SpotHero facility_id. Save this ID with the matching location in your system. Other guides explain how to use facility IDs with reservation endpoints.

Your system may already have its own ID for each location. Match each SpotHero facility to the correct location in your system, then save both IDs together. You can use a lookup table or another method that your team already uses to match locations. If your system does not have its own facility ID, you can use SpotHero's facility_id as the ID in your system.

1. Get the facilities you can access

Call the Get list of facilities endpoint:

GET /v2/facilities
Authorization: Bearer <access_token>

2. Read the response and match locations

The response has a data list. Each item is one facility. By default, each item includes the SpotHero facility_id and facility name.

{
  "data": [
    {
      "facility_id": "cf_01hgeb24jxfn092zyey1ws6w3a",
      "name": "Avenue E & Third Gas Station"
    }
  ],
  "@next": null
}

Use the facility name as a reference for a person to identify the matching location in your system. Do not automatically match facilities by name. A person should confirm each match using your team's location records, then save the relationship between your location ID and the SpotHero facility_id. For example:

Your location ID	Your location name	SpotHero facility ID
garage-42	Avenue E Garage	cf_01hgeb24jxfn092zyey1ws6w3a

The names in your system and SpotHero may not be identical. SpotHero facility names can also change, so do not use a name as a long-term identifier. Once you have confirmed a match, use the saved SpotHero facility_id for future API requests. Repeat this for every facility in the response that you have access to.

3. Get all facilities

The facility list can have more than one page. The default page size is 25. You can set page_size from 10 to 100.

If @next has a URL, request that URL to get the next page. Keep following the returned URL until @next is null. Use the URL exactly as returned; it contains the cursor for the next page. Add the facilities from every page to your matching process.

For example, a response might contain this @next value:

{
  "@next": "/v2/facilities?last_facility_id=cf_01hgeb24jxfn092zyey1ws6w3a&page_size=25"
}

Request that path on the same API host to get the next page:

GET https://integrations.staging.spothero.com/v2/facilities?last_facility_id=cf_01hgeb24jxfn092zyey1ws6w3a&page_size=25
Authorization: Bearer <access_token>

The cursor shown here is an example. In your integration, use the actual @next value from the response. Do not make up or change the cursor.

Optional facility details

The basic request gives you the SpotHero ID and name. You can request optional facility details with the include parameter. The available projections are:

Projection	Additional response field	Details
location	address	An object with address, city, state, zipcode, and timezone. Some values may be null.
operator_facility_id	operator_facility_id	The facility ID provided by the operator, if one is available.

Request one or both projections like this:

GET /v2/facilities?include=location,operator_facility_id

For example, these details can help you confirm which of your locations matches a SpotHero facility:

{
  "data": [
    {
      "facility_id": "cf_01hgeb24jxfn092zyey1ws6w3a",
      "name": "Avenue E & Third Gas Station",
      "address": {
        "address": "300 Avenue E",
        "city": "San Antonio",
        "state": "TX",
        "zipcode": "78205",
        "timezone": "America/Chicago"
      },
      "operator_facility_id": "operator-1005"
    }
  ],
  "@next": null
}

Optional facility data

You need access to a projection to receive its data. If you request a projection that your account cannot access, the API ignores it and returns the basic facility fields. Contact your SpotHero integration representative if you need access to an additional projection.

How often to check for facilities

Facility details do not usually change often. For most integrations, checking this endpoint twice a day is a reasonable starting point. You do not need to call it before every reservation request. Save the facility IDs and use them for your other API requests between checks.