BirdEye PowerShell Module

A PowerShell module for pulling review data, ratings, and sentiment insights from the BirdEye Reputation Management API.

---

Project Structure

BirdEyeAPI/
├── BirdEye/                        # PowerShell module
│   ├── BirdEye.psd1                # Module manifest
│   ├── BirdEye.psm1                # Module loader
│   ├── Private/
│   │   └── Invoke-BirdEyeApi.ps1  # Internal HTTP helper
│   └── Public/
│       ├── Get-BirdEyeConfig.ps1
│       ├── Set-BirdEyeConfig.ps1
│       ├── Get-BirdEyeLocations.ps1
│       ├── Get-BirdEyeReviews.ps1
│       ├── Get-BirdEyeRatings.ps1
│       ├── Get-BirdEyeDashboard.ps1
│       └── Get-BirdEyeKeywordInsights.ps1
├── config/
│   ├── birdeye.config.json         # Your credentials — gitignored
│   └── birdeye.config.example.json # Template (safe to commit)
├── examples/                       # Standalone scripts (pre-module reference)
├── logs/                           # Output logs — gitignored
├── source/
│   └── birdeye.apib                # Full BirdEye API Blueprint reference
├── .gitignore
└── README.md

---

Requirements

• PowerShell 5.1+ or PowerShell 7+
• A BirdEye account with API access
• Your API key and parent Business ID from the BirdEye dashboard

---

Installation

1. Clone or download this repository

git clone <repo-url> BirdEyeAPI
cd BirdEyeAPI

2. Create your config file

Copy the example config and fill in your credentials:

Copy-Item config/birdeye.config.example.json config/birdeye.config.json

Edit config/birdeye.config.json:

{
  "ApiKey": "YOUR_BIRDEYE_API_KEY_HERE",
  "BusinessId": "YOUR_PARENT_BUSINESS_ID_HERE",
  "DefaultSources": [ "google" ],
  "DefaultPageSize": 100
}

Never commit birdeye.config.json — it is excluded by .gitignore.

Alternatively, use Set-BirdEyeConfig to create the file programmatically:

Import-Module .\BirdEye\BirdEye.psd1
Set-BirdEyeConfig -ApiKey "abc123" -BusinessId "175132079741026"

3. Import the module

Import-Module .\BirdEye\BirdEye.psd1

To import automatically in every session, add the above line to your $PROFILE.

---

Configuration

Config file fields

Field	Required	Description
ApiKey	Yes	Your BirdEye API key
BusinessId	Yes	Parent business ID (12–15 digit number)
DefaultSources	No	Review sources used when -Sources is not specified. Default: ["google"]
DefaultPageSize	No	Records per paginated request. Max 100. Default: 100

Config file resolution order

All functions resolve the config file in this order:

1. -Config parameter (pre-loaded object)
2. BIRDEYE_CONFIG_PATH environment variable
3. <module-root>/../config/birdeye.config.json (default)

Finding your credentials

Log in to app.birdeye.com:

• API Key: Settings → Integrations → API
• Business ID: Settings → Business Info (the 12–15 digit number)

---

Functions

Get-BirdEyeRatings

Returns average ratings for all locations over a rolling date window. Locations with no reviews in the window are included with ReviewCount = 0.

# 7-day ratings (default)
$result = Get-BirdEyeRatings

# View as a table
$result.Locations | Format-Table Location, AverageRating, ReviewCount

# 30-day, multiple sources
$result = Get-BirdEyeRatings -DaysBack 30 -Sources @("google", "facebook")

# Export to JSON
Get-BirdEyeRatings -DaysBack 7 -OutputPath ".\ratings_$(Get-Date -Format yyyyMMdd).json"

# Find underperforming locations
$result.Locations | Where-Object { $_.AverageRating -lt 4 -and $_.ReviewCount -gt 0 }

Returns a PSCustomObject with:

Property	Description
GeneratedAt	ISO 8601 timestamp
DaysBack	The window used
DateRange	{ From, To }
Sources	Sources queried
TotalReviews	Sum of all review counts
Locations	Array of per-location summaries (see below)

Each location entry:

Property	Description
LocationId	Child business number
Location	Human-readable store name
ReviewCount	Reviews in the window
AverageRating	Rounded to 2 decimal places, $null if no reviews
MinRating	Lowest rating in window
MaxRating	Highest rating in window

---

Get-BirdEyeLocations

Returns all child locations for the business account.

# All locations
$locations = Get-BirdEyeLocations
$locations | Select-Object label, businessNumber, averageRating | Format-Table

# Last 6 months of activity, sorted by review count
Get-BirdEyeLocations -Months 6 -SortBy count

Returns an array of location objects from the BirdEye API, each including label, businessNumber, averageRating, count, and growth metrics.

---

Get-BirdEyeReviews

Fetches individual reviews with full pagination, optional date filtering, and keyword search.

# Last 30 days (default)
$reviews = Get-BirdEyeReviews

# Custom date range
$reviews = Get-BirdEyeReviews -FromDate "01/01/2026" -ToDate "01/31/2026"

# Reviews for a specific location
$reviews = Get-BirdEyeReviews -BusinessId "176470835477414" -FromDate "02/01/2026"

# Filter by keywords in comment text
$reviews = Get-BirdEyeReviews -CommentFilter @("bathroom", "dirty", "clean")

# Sentiment breakdown
$positive = ($reviews | Where-Object { $_.rating -ge 4 }).Count
$negative = ($reviews | Where-Object { $_.rating -le 2 }).Count

---

Get-BirdEyeDashboard

Returns the overall sentiment dashboard — available to all accounts, no special permissions required.

$dash = Get-BirdEyeDashboard

# All-time stats
$dash.allTime.avgRating.rating
$dash.allTime.reviewCount.count
$dash.allTime.sentiments.positive

# Last 30 days
$dash.last30Days.avgRating.rating

---

Get-BirdEyeKeywordInsights

Returns keyword, theme, or category insights.

Requires the Competitive Insights add-on. Contact BirdEye support if you receive error 4011.

# Top keywords from reviews
Get-BirdEyeKeywordInsights -ReportType Keyword

# Top negative themes
Get-BirdEyeKeywordInsights -ReportType Theme -Sentiment -1 -TopCount 50

# Category sentiment scores
Get-BirdEyeKeywordInsights -ReportType Category -Sources @("google", "yelp")

---

Get-BirdEyeConfig / Set-BirdEyeConfig

# Load config (used internally by all functions)
$cfg = Get-BirdEyeConfig

# Load from a custom path
$cfg = Get-BirdEyeConfig -Path "D:\secrets\birdeye.json"

# Create or update config
Set-BirdEyeConfig -ApiKey "abc123" -BusinessId "175132079741026"

# With all options
Set-BirdEyeConfig `
    -ApiKey "abc123" `
    -BusinessId "175132079741026" `
    -DefaultSources @("google", "facebook") `
    -DefaultPageSize 100

---

Common Workflows

Daily ratings report

Import-Module .\BirdEye\BirdEye.psd1

$result = Get-BirdEyeRatings -DaysBack 1
$result.Locations |
    Where-Object { $_.ReviewCount -gt 0 } |
    Sort-Object AverageRating |
    Format-Table Location, AverageRating, ReviewCount

Export weekly ratings to JSON

Get-BirdEyeRatings -DaysBack 7 -OutputPath ".\logs\ratings_$(Get-Date -Format yyyyMMdd).json"

Find locations with recent 1-star reviews

$locations = Get-BirdEyeLocations

foreach ($loc in $locations) {
    $reviews = Get-BirdEyeReviews -BusinessId $loc.businessNumber `
                                   -FromDate (Get-Date).AddDays(-7).ToString('MM/dd/yyyy')
    $oneStars = $reviews | Where-Object { $_.rating -eq 1 }
    if ($oneStars.Count -gt 0) {
        Write-Host "$($loc.label): $($oneStars.Count) one-star review(s)"
    }
}

Check overall sentiment

$dash = Get-BirdEyeDashboard
[PSCustomObject]@{
    AvgRating     = $dash.last30Days.avgRating.rating
    TotalReviews  = $dash.last30Days.reviewCount.count
    Positive      = $dash.last30Days.sentiments.positive
    Neutral       = $dash.last30Days.sentiments.neutral
    Negative      = $dash.last30Days.sentiments.negative
} | Format-List

---

API Permissions

Function	Endpoint	Special Permission?
Get-BirdEyeRatings	/v1/reports/rating/location + /v1/review/*	No
Get-BirdEyeLocations	/v1/reports/rating/location	No
Get-BirdEyeReviews	/v1/review/businessId/*	No
Get-BirdEyeDashboard	/v1/reports/smb	No
Get-BirdEyeKeywordInsights	/v1/competitors/competitive-insight/*	Yes — Competitive Insights add-on

---

Troubleshooting

Error 4011 — "User is not authorized"

Your account does not have the Competitive Insights add-on. Use Get-BirdEyeRatings, Get-BirdEyeReviews, or Get-BirdEyeDashboard instead, or contact BirdEye support.

Config file not found

Run Set-BirdEyeConfig to create it, or set the BIRDEYE_CONFIG_PATH environment variable to point to your config file.

No reviews returned

• Verify the date range contains actual review activity
• Check that DefaultSources matches where your reviews come from
• Run with -Verbose to see the exact API calls being made

Verbose output

All functions support -Verbose for detailed request logging:

Get-BirdEyeRatings -DaysBack 7 -Verbose

---

API Reference

The full BirdEye API Blueprint is in source/birdeye.apib. Online documentation: developers.birdeye.com