Getting started with the Restaurantology API

Written by Grant Gadoci
Last Update: June 3rd, 2026

The Restaurantology API gives you programmatic access to our database of restaurant concepts (chains and brands), companies (parent groups and operators), their locations, technology stacks, and news.

Think of it as a direct connection to the same intelligence that powers the Chrome Extension and CRM integration — callable from your own tools, on your own schedule.

Key concepts before you start
Getting your API token
Your first API call
Understanding the response
Exploring the API Playground
What you can look up
Searching the database
Credits and limits
Monitoring your usage
Using the API in Salesforce
Using the API in HubSpot
Using the API in Zapier or Make
Using the API in Google Sheets
Using the API in Postman
Common use cases and recipes
Troubleshooting

1. Key concepts before you start

A few terms appear throughout this guide. Here is what they mean.

API An API (Application Programming Interface) is how two software systems talk to each other. When you call the Restaurantology API, you send a request to our servers and receive structured data back. Same idea as loading a web page — except instead of HTML, you receive JSON.

JSON JSON (JavaScript Object Notation) is the format the API uses to return data. It looks like this:

json

{
  "name": "Bart's Chicken Shack",
  "locations": 142,
  "country": "US"
}

Every modern platform — Salesforce, HubSpot, Zapier, Google Sheets, Python, JavaScript — reads JSON natively.

Token (API key) Your token is a 64-character string that proves your identity to the API. Attach it to every request. Keep it private. Anyone who has it can make calls that count against your credit balance.

cURL cURL is a command-line tool that sends HTTP requests. It comes pre-installed on Mac and Linux. On Windows, it is available in PowerShell (version 7+) and in Git Bash. The API Playground generates ready-to-use cURL commands you can paste directly into a terminal.

Credit Each unique data request costs 1 credit. Re-accessing the same record within your credit period is free. Your balance and reset date are always visible in the portal.

2. Getting your API token

Step 1 — Log in to the portal

Go to https://api.restaurantology.io and log in with your credentials.

Step 2 — Go to API Tokens

Click API Tokens in the left-hand navigation menu.

Step 3 — Generate a new token

Click Generate new token. You will be asked for:

Label (optional but recommended) — a name that helps you remember what this token is for. Examples: Salesforce production, HubSpot enrichment, Personal testing.
Expiration date (optional) — leave blank for a token that never expires, or set a date if you want automatic rotation.
IP allow-list (optional) — if your integration runs from a fixed IP address (a Salesforce org, a server), enter it here. The API will reject calls from any other address.

Step 4 — Copy your token immediately

After clicking Save, the full 64-character token is shown only once. Copy it now and store it somewhere safe — a password manager, your CRM’s credential vault, or a secure note. It cannot be retrieved again.

Lost your token? Deactivate it and generate a new one at any time. Old tokens stop working the moment they are deactivated.

3. Your first API call

The fastest way to confirm your token works is a cURL command in your terminal.

Open a terminal (on Mac: Terminal; on Windows: PowerShell or Git Bash) and paste the command below. Replace YOUR_TOKEN_HERE with your actual token and CONCEPT_ID with a valid concept ID (find one using the API Playground’s search feature):

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/concepts/CONCEPT_ID"

A working response starts with:

json

{
  "status": "ok",
  "endpoint": "concepts/{id}",
  "data": {
    "concept": { ... }
  }
}

If you see "status": "error", go to Section 16 (Troubleshooting).

What is the -s flag? It suppresses cURL’s progress bar so only the JSON response is shown. Omit it if you want to see transfer details.

Pretty-printing the output If you have jq installed (available at https://jqlang.github.io/jq/), pipe the output for a more readable result:

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/concepts/CONCEPT_ID" | jq

4. Understanding the response

Every API response returns the same outer structure, regardless of endpoint:

json

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

Field	What it means
`status`	`"ok"` if the call succeeded, `"error"` if something went wrong
`endpoint`	Which endpoint was matched
`data`	The actual content you requested — concept details, locations, search results, etc.
`meta.timestamp`	When the response was generated
`meta.request_id`	A unique ID for this request — include it when contacting support
`meta.credits`	Your current credit balance (only shown if your plan includes credits)
`meta.warnings`	Non-fatal notes, e.g. if a filter value was not recognized

The real content lives inside data. When you call /concepts/{id}, the concept record is at data.concept. When you search, results are at data.concepts and data.companies.

5. Exploring the API Playground

The API Playground (left-hand menu) is the best place to start. It lets you call any endpoint through a simple form — no code, no terminal required.

How it works

Select an endpoint from the dropdown at the top (e.g. “Search”, “Concept details”, “Company locations”)
Fill in the fields that appear
Click Send
The full JSON response appears in the panel on the right

Copy the cURL command

Below the response panel, the Playground shows the exact cURL command used for the call. Click the copy button to grab it. From there you can paste it into a terminal, share it with a developer on your team, or use it as a starting point in Postman, Zapier, Make, or your CRM.

Lookup popups

Some filter fields have a small magnifying glass icon next to them. Clicking it opens a searchable list of valid values:

Metro Areas popup — find and select a metro area name (normalized for use in the urban_area filter). Click Select on any row to insert it into the field.
Tech List popup — find technology names by category. Each row shows the exact Category:DisplayName format required by the tech filter. Click Select to insert it.

6. What you can look up

Concepts — `GET /api/v1/concepts/{id}`

A concept is a restaurant brand or chain. The concept detail endpoint returns the full profile: name, description, service type, unit count, primary geography, and more.

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/concepts/CONCEPT_ID"

Concept locations — `GET /api/v1/concepts/{id}/locations`

Returns the list of open locations for a concept, 30 per page. Use ?page=0, ?page=1, etc. to navigate.

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/concepts/CONCEPT_ID/locations?page=0"

The response includes totalLocations, totalPages, and currentPage so you always know how much data is available.

Concept tech — `GET /api/v1/concepts/{id}/tech`

Returns the technology stack in use at the concept level: POS systems, online ordering platforms, loyalty programs, and more.

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/concepts/CONCEPT_ID/tech"

Concept news — `GET /api/v1/concepts/{id}/news`

Returns recent news articles associated with the concept, organized into top stories and other stories.

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/concepts/CONCEPT_ID/news"

Companies

A company is the parent entity — the restaurant group or holding company that owns one or more concepts. The same four endpoints exist for companies:

GET /api/v1/companies/{id}
GET /api/v1/companies/{id}/locations
GET /api/v1/companies/{id}/tech
GET /api/v1/companies/{id}/news

They work identically to the concept equivalents, just with a company ID.

7. Searching the database

The Search endpoint is the most flexible way to find records. It supports two modes.

Mode 1: Search by website

The simplest mode. Pass a domain and get back matching concepts and companies.

bash

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

exactwebsite is the default method. You do not need to include method=exactwebsite explicitly.

Mode 2: Search by name and filters

The powerful mode. Combine a text query with multiple filters to build precise lists.

Example — QSR chains in Texas and California with more than 50 locations:

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/search?method=name&q=chicken&state=TX,CA&size_min=50"

Example — full-service chains using Square, no text query:

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/search?method=name&service_type=fullservice&tech=Payments:Square&country=us"

Available filters

Filter	What it does	Example values
`q`	Text search on name	`pizza`, `poke kitchen`
`service_type`	Type of restaurant service	`fullservice`, `limitedservice`, `cafeteriasbuffets`, `foodcartstrucks`
`country`	Country of operation	`us`, `ca`
`state`	US state (2-letter codes)	`TX`, `CA,NY,FL`
`state_mode`	How to interpret multiple states	`most` (default), `any`
`size`	Unit count range	`6to20`, `21to100`, `101plus`
`size_min`	Minimum number of units	`50`
`size_max`	Maximum number of units	`200`
`tech`	Technology in use	`POS:Toast`, `Online Ordering:Olo`
`tech_mode`	How to combine multiple techs	`or` (default), `and`
`urban_area`	Metro area (normalized name)	`dallasfortworth`, `chicago`

Multiple values for the same filter are comma-separated: state=TX,CA,NY.

Pagination

Search results return 20 concepts and 20 companies per page. Use ?page=0, ?page=1, etc.

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/search?method=name&q=burger&page=2"

The response always includes totalConcepts, totalCompanies, currentPage, and totalPages.

8. Credits and limits

How credits work

Every unique API call uses 1 credit. “Unique” means you are accessing a record or page you have not accessed in the current credit period.

Re-accessing the same record is free. Call /concepts/BCS001 on Monday and again on Wednesday — the second call costs nothing. It is recognized as a re-access.

For paginated location results, each page is tracked separately. Page 0 and Page 1 of the same concept’s locations count as two distinct calls.

Search calls always cost 1 credit. There is no re-access benefit for search.

Checking your balance

Your remaining credits appear in every API response under meta.credits:

json

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

You can also check your balance at any time in the Dashboard or Usage Report sections of the portal.

Rate limit

You can make 1 request per second per token. If you need higher throughput, use multiple tokens — each token has its own rate limit counter.

If you exceed the limit, the API returns HTTP 429:

“Rate limit: please wait at least 1 second between requests.”

Pause for a second and retry the same request.

9. Monitoring your usage

Dashboard

The Dashboard (first item in the left menu) shows:

API calls in the last 24 hours and last 7 days
Credits remaining vs. total
Number of active tokens in the last 30 days
Hourly call volume (last 24h) and daily call volume (last 7 days)

Usage Report

The Usage Report gives you a detailed breakdown of all API activity. Use the period selector at the top to switch between Last 7 days, Last 30 days, and Last 90 days.

From here you can see which endpoints are called most often, which tokens are most active, a full history of the last 100 calls in the selected period (including IP address), and how many re-access calls occurred.

This is the right place to spot unexpected activity — a token being used from an IP you don’t recognize, or a credit balance draining faster than expected.

10. Using the API in Salesforce

Salesforce can call external APIs two ways: Apex callouts (code) and Flow HTTP Callout actions (no-code, available in Spring ’23 and later).

Prerequisite — Remote Site Settings

Before any outbound callout will work, add https://api.restaurantology.io to Setup → Security → Remote Site Settings. This is a one-time step.

Option A: Flow HTTP Callout (no-code)

Recommended for admins who prefer not to write code.

Go to Setup → Process Automation → Flows
Create a new Record-Triggered Flow (e.g. triggered when an Account is created or updated)
Add an Action element and choose HTTP Callout
Create a new HTTP Callout definition:
- Name: Restaurantology Search
- URL: https://api.restaurantology.io/api/v1/search
- Method: GET
- Headers: Add Authorization with value Bearer YOUR_TOKEN_HERE
Map the query parameters (e.g. q → the Account’s website field, method → exactwebsite)
Parse the response and map data.concepts[0] or data.companies[0] fields to Account fields

Best practice: Store your token in a Named Credential or Custom Metadata Type rather than hardcoding it in the flow. Rotation becomes a one-field update instead of a flow edit.

Option B: Apex HTTP Callout (developer)

apex

HttpRequest req = new HttpRequest();
req.setEndpoint('https://api.restaurantology.io/api/v1/search?method=exactwebsite&q='
    + EncodingUtil.urlEncode(website, 'UTF-8'));
req.setMethod('GET');
req.setHeader('Authorization', 'Bearer YOUR_TOKEN_HERE');
req.setTimeout(10000);

Http http = new Http();
HttpResponse res = http.send(req);

if (res.getStatusCode() == 200) {
    Map<String, Object> body =
        (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
    Map<String, Object> data =
        (Map<String, Object>) body.get('data');
    List<Object> concepts = (List<Object>) data.get('concepts');
    // process concepts...
}

Storing the token securely:

Go to Setup → Named Credentials
Create a new Named Credential:
- Label: Restaurantology API
- URL: https://api.restaurantology.io
- Identity Type: Named Principal
- Authentication Protocol: No Authentication
- Custom Header: Authorization = Bearer YOUR_TOKEN_HERE
Reference it in Apex as callout:Restaurantology_API/api/v1/search?...

Suggested enrichment fields on the Account object

Salesforce field	API source
`Restaurantology_Concept_ID__c`	`data.concepts[0].id` from search
`Total_Locations__c`	`data.concept.totalLocations` from concept detail
`Service_Type__c`	`data.concept.serviceType` from concept detail
`Restaurantology_Last_Enriched__c`	Today’s date (set in Flow or Apex)

11. Using the API in HubSpot

HubSpot supports external API calls through Custom Coded Actions in Workflows. This requires Operations Hub Professional or Enterprise.

Setting up a Custom Coded Action

Go to Automation → Workflows
Create or open a workflow (Contact-based, Company-based, or Deal-based)
Add an action: Custom code (under the “Advanced” category)
Choose Node.js 18.x as the language
Under Secrets, add RESTAURANTOLOGY_TOKEN with your API token as the value
Use the following code:

javascript

const axios = require('axios');

exports.main = async (event, callback) => {
  const website = event.inputFields['domain'];

  const response = await axios.get(
    'https://api.restaurantology.io/api/v1/search',
    {
      params: { q: website, method: 'exactwebsite' },
      headers: { Authorization: `Bearer ${process.env.RESTAURANTOLOGY_TOKEN}` }
    }
  );

  const data = response.data.data;
  const concept = data.concepts && data.concepts[0];

  callback({
    outputFields: {
      restaurantology_concept_id: concept ? concept.id : null,
      restaurantology_total_locations: concept ? concept.totalLocations : null,
    }
  });
};

Map the output fields to HubSpot contact or company properties
Add an Input field that passes the company domain into domain

Tip: Add a condition before the custom code action to check that domain is not empty. This avoids consuming credits on incomplete records.

Token storage

Use the Secrets tab in the Custom Code editor — not the code itself — to store your token. This keeps it out of the source and allows rotation without editing the workflow.

Suggested use cases in HubSpot

Deal created → enrich the associated Company record with concept size and tech stack
Form submission → check if the submitting domain is a known restaurant brand and set an “Industry: Restaurant” property
Weekly data refresh → schedule a workflow to re-enrich your top restaurant accounts

12. Using the API in Zapier or Make

Both Zapier and Make (formerly Integromat) support HTTP requests that work with any REST API.

Zapier — Webhooks by Zapier (GET)

Add a Webhooks by Zapier step to your Zap
Choose GET
Set the URL to https://api.restaurantology.io/api/v1/search
Under Headers, add:
- Key: Authorization
- Value: Bearer YOUR_TOKEN_HERE
Under Query String Params, add:
- method: exactwebsite
- q: use a variable from a previous step (e.g. the website field from a form submission)
In the next step, reference fields from the JSON response using dot notation

Example Zap: New HubSpot Company → GET Restaurantology search by domain → Update HubSpot Company with location count and service type

Make — HTTP module

Add an HTTP → Make a Request module
Set:
- URL: https://api.restaurantology.io/api/v1/search
- Method: GET
- Headers: Authorization: Bearer YOUR_TOKEN_HERE
- Query String: method=exactwebsite&q={{domain variable}}
Enable Parse response — Make will automatically map the JSON fields
Connect the output to any downstream module (Google Sheets, Salesforce, Slack, etc.)

Tip for Make: Use the JSON → Parse JSON module to navigate deeply nested fields like data.concepts.0.name.

13. Using the API in Google Sheets

You can pull Restaurantology data directly into a Google Sheet using Apps Script.

Setup

Open your Google Sheet
Go to Extensions → Apps Script
Paste the following script, replacing YOUR_TOKEN_HERE with your token:

javascript

function restaurantologySearch(domain) {
  const token = 'YOUR_TOKEN_HERE';
  const url = 'https://api.restaurantology.io/api/v1/search?method=exactwebsite&q='
              + encodeURIComponent(domain);

  const options = {
    method: 'get',
    headers: { 'Authorization': 'Bearer ' + token },
    muteHttpExceptions: true
  };

  const response = UrlFetchApp.fetch(url, options);
  const json = JSON.parse(response.getContentText());

  if (json.status !== 'ok') return 'Error: ' + json.message;

  const concept = json.data.concepts && json.data.concepts[0];
  if (!concept) return 'Not found';

  return concept.name + ' | Locations: ' + (concept.totalLocations || 'N/A');
}

Save the script (Ctrl+S / Cmd+S)

Using the function

Use =restaurantologySearch(A2) in any cell, where A2 contains a website domain. The function returns a summary string.

To return separate fields and use them in individual columns, return an array and use INDEX():

javascript

function restaurantologySearchArray(domain) {
  // ... same fetch code ...
  if (!concept) return [['Not found', '', '']];
  return [[concept.name, concept.totalLocations || 0, concept.serviceType || '']];
}

Then use =INDEX(restaurantologySearchArray(A2), 1, 1) for the name, 1, 2 for location count, and so on.

Important: Google’s free quota allows approximately 20,000 UrlFetchApp calls per day. For large sheets, add a check to avoid re-fetching rows that are already enriched.

14. Using the API in Postman

Postman is a tool for testing and exploring APIs. Download it free at https://www.postman.com.

Importing the token

In Postman, create a new Collection called Restaurantology API
Go to the collection’s Variables tab and add a variable:
- Name: token
- Current value: your 64-character token
In each request, set Authorization to Bearer Token and use {{token}} as the value

This way you only need to update the token in one place when you rotate it.

Setting the base URL as a variable

Add another collection variable:

Name: baseUrl
Current value: https://api.restaurantology.io/api/v1

Each request URL becomes {{baseUrl}}/concepts/{{conceptId}} — reusable across your collection.

Running a search request

Create a new GET request inside the collection
Set the URL to {{baseUrl}}/search
Under Params, add:
- method: name
- q: chicken
- country: us
- state: TX
Click Send

The response appears in the bottom panel. Click nested fields to expand them, or use the Visualize tab to render JSON as a table.

Importing cURL commands from the Playground

The API Playground generates ready-to-copy cURL commands. Import them directly into Postman:

Copy the cURL command from the Playground
In Postman, click Import (top left)
Select Raw text and paste the cURL command
Postman converts it automatically into a request with the correct URL, method, and headers

15. Common use cases and recipes

Recipe 1: Enrich an account list with unit counts

You have a spreadsheet of restaurant companies identified by website domain. You want to add location counts.

Call GET /api/v1/search?q=DOMAIN for each row
Take the first result from data.concepts or data.companies
Write the id back to the row for future lookups
Call GET /api/v1/concepts/{id} to get the full profile including unit count

The search gives you the ID. The detail call gives you the complete record. If you already have the concept ID from a previous enrichment, skip to step 4 — it saves credits.

Recipe 2: Build a prospect list of mid-size chains using a specific POS

Find limited-service chains with 20 to 100 locations that use Toast.

bash

curl -s \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  "https://api.restaurantology.io/api/v1/search?method=name&service_type=limitedservice&size_min=20&size_max=100&tech=POS:Toast&country=us"

Page through results using &page=1, &page=2, etc. until currentPage equals totalPages - 1.

Recipe 3: Track technology changes for key accounts

For each concept in your CRM:

Call GET /api/v1/concepts/{id}/tech on a weekly schedule
Compare the returned tech list to what you stored last week
If a technology appears or disappears, trigger an alert or update the CRM record

Recipe 4: Monitor news for key accounts

Run a daily or weekly job that calls GET /api/v1/concepts/{id}/news for your top accounts. Check if topStories contains any articles newer than your last run. Push new articles to a Slack channel or create CRM activities.

Recipe 5: Website-to-account matching on inbound form submissions

When a prospect submits a form with their company website:

Send GET /api/v1/search?q=DOMAIN immediately via your integration
If a concept or company is found, auto-populate the CRM record with name, size, and service type
Set a custom “Restaurant verified” flag on the record
Route the lead to the right sales territory based on location count or geography

16. Troubleshooting

“Missing or invalid Authorization header”

Your Authorization header is not formatted correctly. It must be exactly:

Authorization: Bearer YOUR_64_CHAR_TOKEN

Check for extra spaces, a missing “Bearer ” prefix (note the space after Bearer), or an accidentally truncated token.

“Invalid token format”

The token must be exactly 64 hexadecimal characters (letters a–f and digits 0–9 only). Confirm you copied the full token and that no line breaks or spaces were introduced.

“Invalid, expired or inactive token”

One of these is true:

The token has passed its expiration date — generate a new one
The token was manually deactivated in the portal
You are using a token that belongs to a different account

“Client IP not in token allow list”

Your token has an IP restriction and the request is coming from an address not on the list. Update the allow-list in API Tokens to include your current IP, or remove the restriction if you are testing from a dynamic IP.

“No active subscription found for this account”

Your account does not have an active API subscription. Contact your account manager or check your subscription status in the portal.

HTTP 429 — “Monthly credit limit reached”

Your credit balance is at zero. The response includes creditsUsed and creditsTotal. Credits reset at the start of your next billing period (visible in the Usage Report under Credit period).

HTTP 429 — “Rate limit” message

You are sending more than 1 request per second with the same token. Add a sleep(1) or equivalent delay between calls, or distribute requests across multiple tokens.

“Endpoint not found”

The URL path does not match any known route. Common mistakes:

Missing /api/v1/ prefix
Typo in the resource name (e.g. /concept/ instead of /concepts/)
Using POST on a GET-only endpoint

Check the API Reference for exact paths.

The `data` field is empty or null

For concept and company detail calls, if the ID does not match a valid record, data.concept or data.company is returned as null and a warning appears in meta.warnings. Confirm the ID is correct — it should come from a search result or the Playground.

My Salesforce callout is failing with “Unauthorized endpoint”

Add https://api.restaurantology.io to Setup → Security → Remote Site Settings. This is a one-time step required before any outbound HTTP call from Salesforce to an external domain.

The JSON response looks garbled in my terminal

Use jq to pretty-print it:

bash

curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.restaurantology.io/api/v1/..." | jq

Or paste the raw JSON into https://jsonlint.com for a formatted, clickable view.

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

Knowledge Hub