Knowledge Hub

Version: v1 Base URL: https://api.restaurantology.io/api/v1 Protocol: HTTPS required

---

Table of contents

1. Authentication
2. Rate limiting
3. Credit system
4. Response envelope
5. Error handling
6. Endpoints
   • GET /concepts/{id}
   • GET /concepts/{id}/locations
   • GET /concepts/{id}/tech
   • GET /concepts/{id}/news
   • GET /companies/{id}
   • GET /companies/{id}/locations
   • GET /companies/{id}/tech
   • GET /companies/{id}/news
   • GET /search
7. Search filters reference
8. Backoffice

---

1. Authentication

Every request must include a Bearer token in the Authorization header.

Authorization: Bearer <token>

Tokens are 64-character hexadecimal strings generated in the API Tokens section of the portal. Each token is tied to your account and can optionally be restricted to specific IP addresses.

Example:

bash

curl -H "Authorization: Bearer 4a8f3c1e...d09b72" \
     "https://api.restaurantology.io/api/v1/concepts/BCS001"

Token validation rules:

• Must be exactly 64 hexadecimal characters
• Must be active and not expired
• If the token has an IP allow-list configured, the request must originate from a listed IP

---

2. Rate limiting

1 request per second per token.

Exceeding this limit returns HTTP 429:

json

{
  "status": "error",
  "message": "Rate limit: please wait at least 1 second between requests."
}

The limit is enforced per token, not per IP address. If you need higher throughput, use multiple tokens — each has its own rate limit counter.

---

3. Credit system

Each API call consumes 1 credit from your account balance. Credits reset according to the period configured for your subscription.

Re-access (free calls)

Re-accessing the same resource within the same credit period is free. A call is considered a re-access when all of the following match a previous call in the current period:

Endpoint type	Re-access condition
/concepts/{id}, /companies/{id}, /*/tech, /*/news	Same endpoint + same entity ID
/*/locations	Same endpoint + same entity ID + same page number
/search	Not eligible — each search costs 1 credit

Re-access calls are logged but marked as non-counting. The credit counter in the response reflects this in real time.

Credit response

When your account has a credit plan, every response includes a credits object in meta:

json

"meta": {
  "credits": {
    "used": 42,
    "remaining": 458,
    "total": 500,
    "period": "monthly (resets 1st)"
  }
}

Credit periods

Label	Description
monthly (resets 1st)	Resets on the 1st of each month
monthly (resets 7th)	Resets on the 7th of each month
monthly (resets 10th)	Resets on the 10th of each month
monthly (resets 14th)	Resets on the 14th of each month
monthly (resets 20th)	Resets on the 20th of each month
monthly (resets 21st)	Resets on the 21st of each month
monthly (resets 28th)	Resets on the 28th of each month
rolling 7 days	Sliding 7-day window
rolling 14 days	Sliding 14-day window
rolling 30 days	Sliding 30-day window
rolling 60 days	Sliding 60-day window
rolling 90 days	Sliding 90-day window

Credit limit error

When credits are exhausted:

json

{
  "status": "error",
  "message": "Monthly credit limit reached.",
  "creditsUsed": 500,
  "creditsTotal": 500
}

---

4. Response envelope

All successful responses share the same JSON envelope:

json

{
  "status": "ok",
  "endpoint": "concepts/{id}",
  "data": { ... },
  "meta": {
    "timestamp": "2026-03-14T10:23:45+00:00",
    "request_id": "a1b2c3d4e5f6g7h8",
    "credits": {
      "used": 42,
      "remaining": 458,
      "total": 500,
      "period": "monthly (resets 1st)"
    }
  }
}

Field	Description
status	"ok" for successful responses
endpoint	Human-readable name of the matched route
data	The response payload — structure varies by endpoint
meta.timestamp	ISO 8601 timestamp of the response
meta.request_id	Unique identifier for this request — include it when contacting support
meta.credits	Credit usage — present only if your account has a credit plan
meta.warnings	Array of non-fatal warnings (e.g. unrecognized filter values)

---

5. Error handling

All errors return a JSON body with "status": "error":

json

{
  "status": "error",
  "message": "Human-readable description of the error."
}

HTTP status codes

Code	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — missing, invalid, or expired token
403	Forbidden — IP not in allow-list, or no active subscription
404	Not found — endpoint or record does not exist
405	Method not allowed
429	Too many requests — rate limit or credit limit reached
503	Service unavailable — temporary backend issue

---

6. Endpoints

GET /concepts/{id}

Retrieve the full profile of a restaurant concept (chain or brand).

Request:

GET /api/v1/concepts/{id}
Authorization: Bearer <token>

Example:

bash

curl -s \
  -H "Authorization: Bearer <token>" \
  "https://api.restaurantology.io/api/v1/concepts/BCS001"

Example response:

json

{
  "status": "ok",
  "endpoint": "concepts/{id}",
  "data": {
    "concept": {
      "id": "BCS001",
      "name": "Bart's Chicken Shack",
      "slug": "barts-chicken-shack",
      "description": "Fast-casual chicken chain operating across the Southern and Midwest US.",
      "serviceType": "limitedservice",
      "totalLocations": 142,
      "primaryState": "TX",
      "country": "us",
      "website": "bartschickenshack.com",
      "companyId": "BCH-PARENT"
    }
  },
  "meta": {
    "timestamp": "2026-03-14T10:23:45+00:00",
    "request_id": "a1b2c3d4e5f6g7h8",
    "credits": {
      "used": 43,
      "remaining": 457,
      "total": 500,
      "period": "monthly (resets 1st)"
    }
  }
}

If the ID does not match a valid record, concept is returned as null and a warning appears in meta.warnings.

---

GET /concepts/{id}/locations

Retrieve the list of open locations for a concept. Results are paginated — 30 locations per page.

Request:

GET /api/v1/concepts/{id}/locations?page=0
Authorization: Bearer <token>

Query parameters:

Parameter	Type	Default	Description
page	integer	0	0-indexed page number

Example:

bash

curl -s \
  -H "Authorization: Bearer <token>" \
  "https://api.restaurantology.io/api/v1/concepts/BCS001/locations?page=0"

Example response:

json

{
  "status": "ok",
  "endpoint": "concepts/{id}/locations",
  "data": {
    "locations": [
      {
        "id": "BCS001-LOC-001",
        "name": "Bart's Chicken Shack",
        "address": "4521 Greenway Blvd",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "country": "us",
        "phone": "512-555-0182",
        "status": "open"
      },
      {
        "id": "BCS001-LOC-002",
        "name": "Bart's Chicken Shack",
        "address": "800 Commerce St",
        "city": "Dallas",
        "state": "TX",
        "zip": "75202",
        "country": "us",
        "phone": "214-555-0341",
        "status": "open"
      }
    ],
    "totalLocations": 142,
    "closedLocations": [
      {
        "id": "BCS001-LOC-099",
        "address": "12 River Oaks Plaza",
        "city": "Houston",
        "state": "TX",
        "status": "closed"
      }
    ],
    "totalClosed": 6,
    "currentPage": 0,
    "totalPages": 5
  },
  "meta": {
    "timestamp": "2026-03-14T10:24:01+00:00",
    "request_id": "b2c3d4e5f6g7h8i9",
    "credits": {
      "used": 44,
      "remaining": 456,
      "total": 500,
      "period": "monthly (resets 1st)"
    }
  }
}

Response fields:

Field	Description
locations	Array of open location objects for the current page
totalLocations	Total count of open locations across all pages
closedLocations	Array of recently closed locations
totalClosed	Total count of closed locations
currentPage	0-indexed page returned (clamped to valid range)
totalPages	Total number of pages available

Credit note: Each page is counted as a separate credit. Revisiting the same page within the credit period is free.

---

GET /concepts/{id}/tech

Retrieve the technology stack associated with a concept.

Request:

GET /api/v1/concepts/{id}/tech
Authorization: Bearer <token>

Example:

bash

curl -s \
  -H "Authorization: Bearer <token>" \
  "https://api.restaurantology.io/api/v1/concepts/BCS001/tech"

Example response:

json

{
  "status": "ok",
  "endpoint": "concepts/{id}/tech",
  "data": {
    "tech": [
      {
        "category": "POS",
        "displayName": "Toast",
        "verified": true,
        "verificationMethod": "website"
      },
      {
        "category": "Online Ordering",
        "displayName": "Toast Online Ordering",
        "verified": true,
        "verificationMethod": "website"
      },
      {
        "category": "Loyalty",
        "displayName": "Toast Loyalty",
        "verified": false,
        "verificationMethod": null
      }
    ]
  },
  "meta": {
    "timestamp": "2026-03-14T10:24:15+00:00",
    "request_id": "c3d4e5f6g7h8i9j0",
    "credits": {
      "used": 45,
      "remaining": 455,
      "total": 500,
      "period": "monthly (resets 1st)"
    }
  }
}

---

GET /concepts/{id}/news

Retrieve news articles associated with a concept.

Request:

GET /api/v1/concepts/{id}/news
Authorization: Bearer <token>

Example:

bash

curl -s \
  -H "Authorization: Bearer <token>" \
  "https://api.restaurantology.io/api/v1/concepts/BCS001/news"

Example response:

json

{
  "status": "ok",
  "endpoint": "concepts/{id}/news",
  "data": {
    "topStories": [
      {
        "title": "Bart's Chicken Shack announces 20-unit expansion into the Midwest",
        "url": "https://www.example-news.com/barts-chicken-shack-expansion",
        "publishedAt": "2026-02-28T09:00:00+00:00",
        "source": "QSR Magazine"
      }
    ],
    "otherStories": [
      {
        "title": "Bart's Chicken Shack launches new loyalty program",
        "url": "https://www.example-news.com/barts-loyalty",
        "publishedAt": "2026-01-15T14:30:00+00:00",
        "source": "Nation's Restaurant News"
      }
    ],
    "totalTopStories": 1,
    "totalOtherStories": 7
  },
  "meta": {
    "timestamp": "2026-03-14T10:24:30+00:00",
    "request_id": "d4e5f6g7h8i9j0k1"
  }
}

Response fields:

Field	Description
topStories	Most relevant news items
otherStories	Additional news items
totalTopStories	Count of top stories
totalOtherStories	Count of other stories

---

GET /companies/{id}

Retrieve the full profile of a restaurant company (parent entity or restaurant group).

Request:

GET /api/v1/companies/{id}
Authorization: Bearer <token>

Example:

bash

curl -s \
  -H "Authorization: Bearer <token>" \
  "https://api.restaurantology.io/api/v1/companies/BCH-PARENT"

Example response:

json

{
  "status": "ok",
  "endpoint": "companies/{id}",
  "data": {
    "company": {
      "id": "BCH-PARENT",
      "name": "BCH Restaurant Group",
      "description": "Operator of Bart's Chicken Shack and Sunny Bowl.",
      "totalLocations": 209,
      "country": "us",
      "website": "bchrestaurantgroup.com",
      "concepts": ["BCS001", "SB002"]
    }
  },
  "meta": {
    "timestamp": "2026-03-14T10:25:00+00:00",
    "request_id": "e5f6g7h8i9j0k1l2",
    "credits": {
      "used": 46,
      "remaining": 454,
      "total": 500,
      "period": "monthly (resets 1st)"
    }
  }
}

If the ID does not match a valid record, company is returned as null and a warning appears in meta.warnings.

---

GET /companies/{id}/locations

Retrieve the list of locations operated by a company. Pagination works identically to /concepts/{id}/locations — 30 locations per page, same page parameter, same response structure.

Request:

GET /api/v1/companies/{id}/locations?page=0
Authorization: Bearer <token>

Response data: Same structure as concept locations — locations, totalLocations, closedLocations, totalClosed, currentPage, totalPages.

---

GET /companies/{id}/tech

Retrieve the technology stack associated with a company.

Request:

GET /api/v1/companies/{id}/tech
Authorization: Bearer <token>

Response data: Same structure as concept tech — an array of tech objects with category, displayName, verified, and verificationMethod.

---

GET /companies/{id}/news

Retrieve news articles associated with a company.

Request:

GET /api/v1/companies/{id}/news
Authorization: Bearer <token>

Response data: Same structure as concept news — topStories, otherStories, totalTopStories, totalOtherStories.

---

GET /search

Search for concepts and companies. Supports two modes: exact website and name + filters.

Accepts both GET and POST. When using POST, parameters in the body override any query-string parameters of the same name.

Core parameters:

Parameter	Type	Description
method	string	exactwebsite (default) or name. Aliases: 1 = exactwebsite, 2 = name
q	string	Search query. Required for exactwebsite. Optional for name if at least 2 filter criteria are provided
page	integer	0-indexed page number (default: 0). 20 results per page

method=exactwebsite

Matches concepts and companies by their website domain. Only q is used — all filter parameters are ignored.

bash

curl -s \
  -H "Authorization: Bearer <token>" \
  "https://api.restaurantology.io/api/v1/search?q=bartschickenshack.com"

Example response:

json

{
  "status": "ok",
  "endpoint": "search",
  "data": {
    "concepts": [
      {
        "id": "BCS001",
        "name": "Bart's Chicken Shack",
        "serviceType": "limitedservice",
        "totalLocations": 142,
        "primaryState": "TX",
        "country": "us",
        "website": "bartschickenshack.com"
      }
    ],
    "companies": [],
    "totalConcepts": 1,
    "totalCompanies": 0,
    "currentPage": 0,
    "totalPages": 1
  },
  "meta": {
    "timestamp": "2026-03-14T10:26:00+00:00",
    "request_id": "f6g7h8i9j0k1l2m3",
    "credits": {
      "used": 47,
      "remaining": 453,
      "total": 500,
      "period": "monthly (resets 1st)"
    }
  }
}

method=name

Searches by concept or company name with optional filters. If q is omitted, at least 2 filter criteria must be provided from: service_type, country, state, tech, urban_area, size / size_min / size_max (the size parameters together count as one criterion).

bash

curl -s \
  -H "Authorization: Bearer <token>" \
  "https://api.restaurantology.io/api/v1/search?method=name&q=chicken&country=us&state=TX,CA&service_type=limitedservice"

Example response:

json

{
  "status": "ok",
  "endpoint": "search",
  "data": {
    "concepts": [
      {
        "id": "BCS001",
        "name": "Bart's Chicken Shack",
        "serviceType": "limitedservice",
        "totalLocations": 142,
        "primaryState": "TX",
        "country": "us",
        "website": "bartschickenshack.com"
      },
      {
        "id": "GG003",
        "name": "Green Ground",
        "serviceType": "limitedservice",
        "totalLocations": 38,
        "primaryState": "CA",
        "country": "us",
        "website": "greenground.com"
      }
    ],
    "companies": [
      {
        "id": "BCH-PARENT",
        "name": "BCH Restaurant Group",
        "totalLocations": 209,
        "country": "us",
        "website": "bchrestaurantgroup.com"
      }
    ],
    "totalConcepts": 14,
    "totalCompanies": 3,
    "currentPage": 0,
    "totalPages": 1
  },
  "meta": {
    "timestamp": "2026-03-14T10:26:30+00:00",
    "request_id": "g7h8i9j0k1l2m3n4",
    "credits": {
      "used": 48,
      "remaining": 452,
      "total": 500,
      "period": "monthly (resets 1st)"
    }
  }
}

Response fields:

Field	Description
concepts	Array of concept results for the current page (max 20)
companies	Array of company results for the current page (max 20)
totalConcepts	Total matching concepts across all pages
totalCompanies	Total matching companies across all pages
currentPage	0-indexed page returned
totalPages	Determined by max(totalConcepts, totalCompanies) / 20, rounded up

Concepts and companies are paginated together using the same page index. The page count is based on whichever result set is larger.

---

7. Search filters reference

Filters are only active when method=name. Multiple values for the same parameter are comma-separated.

---

service_type

Filter by restaurant service type.

Value	Description
fullservice	Full service restaurants
limitedservice	Limited service / fast food
cafeteriasbuffets	Cafeterias and buffets
foodcartstrucks	Food carts and trucks

Example: service_type=fullservice,limitedservice

---

country

Filter by country of primary operation.

Value	Description
us	United States
ca	Canada

Example: country=us

---

state

Filter by US state using 2-letter state codes (uppercase or lowercase). Works with state_mode.

Example: state=TX,CA,NY

---

state_mode

Controls how multiple states are interpreted.

Value	Description
most	(default) Concept or company primarily operates in one of the listed states
any	Concept or company has at least one location in one of the listed states

---

size

Filter by unit count using predefined ranges.

Value	Range
2units	2 units
3to5	3 to 5 units
6to20	6 to 20 units
21to100	21 to 100 units
101plus	More than 100 units

Example: size=6to20,21to100

---

size_min / size_max

Filter by exact minimum and/or maximum unit count. These take priority over size when specified.

Example: size_min=10&size_max=50

When both are provided, they define a custom numeric range. When only one is provided, the other end is open.

---

tech

Filter by technology in use. Values must follow the format Category:DisplayName (case-insensitive). Comma-separate multiple values.

Use the Tech List popup in the API Playground to browse available technology names and their correct format.

Example: tech=POS:Toast,Online%20Ordering:Olo

---

tech_mode

Controls how multiple technologies are combined.

Value	Description
or	(default) Match concepts or companies using any of the listed technologies
and	Match concepts or companies using all of the listed technologies

---

urban_area

Filter by metro area. Values are the normalized metro area name: lowercase, no spaces, no commas.

Use the Metro Areas popup in the API Playground to browse available values.

Example: urban_area=dallasfortworth,houston

---

Filter combination rules

• q alone: text search across all records
• q + filters: text search narrowed by filters
• Filters alone (no q): at least 2 qualifying criteria required (service_type, country, state, tech, urban_area, and the size parameters each count individually; state_mode and tech_mode do not count)
• Unrecognized filter values are silently ignored — a warning is added to meta.warnings

---

8. Backoffice

The portal is accessible at https://api.restaurantology.io after logging in. Four sections are reachable from the left-hand navigation menu.

---

Dashboard

URL: /dashboard

The Dashboard is the entry point of the portal. It shows a real-time snapshot of your API activity.

Metric cards:

Card	Description
API calls (last 24h)	Total calls in the past 24 hours
API calls (last 7 days)	Total calls in the past 7 days
Credits remaining	Current balance out of your total plan allowance, shown as N / Total. Hidden if no credit plan is active
Active tokens (30 days)	Number of distinct tokens that have made at least one call in the last 30 days

Charts:

Chart	Description
Calls per hour — last 24h	Bar chart with 24 hourly slots
Calls per day — last 7 days	Bar chart with 7 daily slots

---

API Tokens

URL: /user_tokens

Manage the tokens associated with your account.

Token list columns:

Column	Description
Token prefix	First 8 characters — identifies the token without exposing the full value
Status	Active or inactive
Created	Creation date
Last used	Timestamp of the most recent call
Usage count	Total calls made with this token
Expiration	Expiry date, if set
IP allow-list	Whether an IP restriction is active

Creating a token:

Click Generate new token. The full 64-character string is shown only once at creation — copy it immediately. Each token can be configured with a label, an optional expiration date, and an optional IP allow-list (one address per line). Requests from unlisted IPs are rejected with HTTP 403.

Revoking a token:

Deactivating a token immediately blocks all further calls using it. This action cannot be undone.

---

Usage Report

URL: /user_tokens_report

Detailed analytics on your API activity. All sections respond to the period selector at the top of the page.

Period selector:

Option	Description
Last 7 days	Data from the past 7 days
Last 30 days	Data from the past 30 days (default)
Last 90 days	Data from the past 90 days

Credit summary cards (shown only if your account has a credit plan):

Card	Description
Credits used	Credits consumed in the current credit period
Credits remaining	Credits still available in the current period
Credit total	Total credits for the period
Credit period	When credits reset

Usage summary cards:

Card	Description
Total calls	Total API calls in the selected period
Unique tokens used	Number of distinct tokens active in the period
Last call	Timestamp of the most recent call

API calls over time: Line chart showing call volume per day across the selected period.

Calls by token: Doughnut chart and table breaking down call counts by token prefix — useful for understanding which integrations are most active.

Endpoint breakdown: Doughnut chart and table showing how calls are distributed across endpoints. Re-access (free) calls are excluded from the breakdown and reported separately below the table.

Column	Description
#	Rank by call volume
API endpoint	Human-readable endpoint name (e.g. GET concepts/{id})
Calls	Number of calls in the selected period
%	Percentage of total endpoint calls

Recent calls: Table showing the last 100 API calls within the selected period, most recent first.

Column	Description
Date	Timestamp of the call
Token	Token prefix used
Endpoint	Endpoint called. Re-access calls appear in italics as “Re-access (free)”. Paginated location calls include the page number (e.g. GET concepts/{id}/locations (page 2))
Record ID	Internal ID of the entity requested — empty for search calls
IP	IP address from which the call originated
Lang	Language parameter passed with the request

---

API Playground

URL: /api_playground

An interactive testing environment for calling every API endpoint directly from the browser — no code required.

How to use it:

1. Select an endpoint from the dropdown at the top
2. Fill in the parameters that appear
3. Click Send
4. The raw JSON response appears in the output panel on the right

Lookup popups:

Metro Areas popup — accessible when the urban_area filter field is active. Displays a searchable table of all available metro areas with their normalized API value (lowercase, no spaces, no commas). Click Select on any row to insert the value into the field.

Tech List popup — accessible when the tech filter field is active. Displays a searchable table of all available technologies organized by category, with the exact Category:DisplayName format required. Click Select on any row to insert the value.

Token for Playground requests: The Playground uses one of your active tokens automatically. Make sure you have at least one active token in the API Tokens section before testing.

Notes:

• The Playground calls the live API. Each non-re-access request consumes 1 credit.
• Responses are the same JSON envelope described in Section 4.
• The meta.credits field in the response is the most reliable way to monitor your balance during testing.

---

For support, include your meta.request_id from the failing response when contacting the Restaurantology team.