Searching Businesses

The search functionality is at the core of Roozna's API, allowing you to find detailed information about businesses. This page will guide you through using the search endpoint to query our extensive database of over 50,000 businesses.

The business model

The business model contains comprehensive information about each company, including its name, description, category, employee count, and more. Here's an overview of the properties you can expect in a business object.

Properties

Name
id
Type
string
Description
Unique identifier for the business.
Name
name
Type
string
Description
The name of the business.
Name
website
Type
string
Description
The website URL of the business.
Name
description
Type
string
Description
A brief description of the business.
Name
category
Type
string
Description
The primary category or industry of the business.
Name
employeeCount
Type
integer
Description
The estimated number of employees in the business.
Name
image
Type
string
Description
URL to the business's logo or primary image.
Name
createdAt
Type
timestamp
Description
Timestamp of when the business record was created in our database.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the business record was last updated.

GET/v1/search

Search businesses

This endpoint allows you to search for businesses based on various criteria. The search is performed across business names, descriptions, and categories.

Required attributes

Name
q
Type
string
Description
The search query string.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of businesses returned (default: 20, max: 100).
Name
page
Type
integer
Description
Page number for pagination (default: 1).
Name
sort
Type
string
Description
Field to sort by (e.g., 'name', 'employeeCount').
Name
filter
Type
string
Description
Additional filtering criteria (e.g., 'category:Technology').

Request

GET

/v1/search

curl -G https://api.roozna.com/v1/search \
  -H "X-API-Key: {your_api_key}" \
  -d q="tech startups" \
  -d limit=10

Response

{
  "results": [
    {
      "id": "b1234567-89ab-cdef-0123-456789abcdef",
      "name": "TechNova Solutions",
      "website": "https://technova.com",
      "description": "Innovative AI-driven solutions for modern businesses",
      "category": "Technology",
      "employeeCount": 50,
      "image": "https://assets.roozna.com/images/technova.png",
      "createdAt": 1636070400,
      "updatedAt": 1651881600
    },
    {
      "id": "c2345678-90cd-efab-1234-567890bcdef0"
      // ...
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalHits": 48,
    "hitsPerPage": 10,
    "nextPage": 2
  }
}

GET/v1/businesses/:id

Retrieve a business

This endpoint allows you to retrieve detailed information about a specific business by providing its unique identifier.

Request

GET

/v1/businesses/b1234567-89ab-cdef-0123-456789abcdef

curl https://api.roozna.com/v1/businesses/b1234567-89ab-cdef-0123-456789abcdef \
  -H "X-API-Key: {your_api_key}"

Response

{
  "id": "b1234567-89ab-cdef-0123-456789abcdef",
  "name": "TechNova Solutions",
  "website": "https://technova.com",
  "description": "Innovative AI-driven solutions for modern businesses",
  "category": "Technology",
  "employeeCount": 50,
  "image": "https://assets.roozna.com/images/technova.png",
  "createdAt": 1636070400,
  "updatedAt": 1651881600
}

Best practices

When using the search endpoint, consider the following best practices:

Use specific and targeted search queries to get more relevant results.
Utilize the filter parameter to narrow down results by category or other attributes.
Implement pagination in your application to handle large result sets efficiently.
Cache frequently accessed business details to reduce API calls and improve performance.

Rate limiting

Be aware that your API usage is subject to rate limiting based on your current plan. Exceeding these limits will result in a 429 Too Many Requests error.

Learn more about rate limiting