Search API

The Search API allows you to query Roozna's extensive database of businesses. You can search for companies based on various criteria such as name, industry, location, and more.

Endpoint

GET /v1/search

Authentication

All requests to the Search API must include your API key in the X-API-Key header.

Request Parameters

Name
q
Type
string
Description
The search query string. This can include company names, keywords, or phrases.
Name
limit
Type
integer
Description
The maximum number of results to return. Default is 20, maximum is 100.
Name
cursor
Type
string
Description
A cursor for pagination. Use the next_cursor from a previous response to get the next page of results.
Name
sort
Type
string
Description
The field to sort results by. Options include relevance (default), name, employee_count, founded_year.
Name
order
Type
string
Description
The order of sorted results. Can be asc (ascending) or desc (descending). Default varies by sort field.
Name
industry
Type
string
Description
Filter results by industry. You can provide multiple industries separated by commas.
Name
location
Type
string
Description
Filter results by location. Can be a city, state, country, or combination.
Name
min_employees
Type
integer
Description
Filter results to companies with at least this many employees.
Name
max_employees
Type
integer
Description
Filter results to companies with at most this many employees.

Response

The API returns a JSON response with the following structure:

Name
results
Type
array
Description
An array of business objects matching the search criteria.
Name
pagination
Type
object
Description
Object containing pagination information.
Name
pagination.total
Type
integer
Description
Total number of results matching the query.
Name
pagination.next_cursor
Type
string
Description
Cursor to use for the next page of results. Null if there are no more results.

Response

{
  "results": [
    {
      "id": "b1234567-89ab-cdef-0123-456789abcdef",
      "name": "TechNova Solutions",
      "website": "https://technova.com",
      "description": "Innovative AI-driven solutions for modern businesses",
      "industry": "Technology",
      "employee_count": 50,
      "location": {
        "city": "San Francisco",
        "state": "CA",
        "country": "United States"
      },
      "founded_year": 2015
    },
    // ... more results
  ],
  "pagination": {
    "total": 1000,
    "next_cursor": "YXJyYXljb25uZWN0aW9uOjEw"
  }
}

Example Usage

Here's an example of how to use the Search API:

Request

GET

/v1/search

curl -G https://api.roozna.com/v1/search \
  -H "X-API-Key: your_api_key" \
  -d q="AI startups" \
  -d industry="Technology" \
  -d location="San Francisco" \
  -d limit=10

The API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with Roozna's servers.

Some common errors you might encounter:

400 Bad Request: Your request was invalid.
401 Unauthorized: Your API key is wrong.
404 Not Found: The specified resource could not be found.
429 Too Many Requests: You have exceeded your rate limit.

For more details on handling errors, see our Error Handling guide.

Rate Limiting

This endpoint is subject to rate limiting. For more information, see our Rate Limiting guide.

Next: Retrieve Business Details