Migrate from the Legacy v1 API to SiteAtlas v2

This guide is for users of the legacy Similarweb API Pro RapidAPI listing:

https://similarweb-api-pro.p.rapidapi.com

The current API is the DataBee SiteAtlas API. New integrations should use the direct gateway or the trademark-free SiteAtlas RapidAPI listing. The url query parameter remains the same, but endpoint paths, authentication context, response envelopes, and several field names have changed.

Migrate the listing as well as the response

Similarweb API Pro also exposes v2-style endpoints. Moving only from its v1 paths to its v2 paths is not the complete long-term migration. The Similarweb API Pro listing contains “Similarweb” in its name, and Similarweb has previously taken down API listings for trademark-related reasons. That creates availability risk for an integration that depends on the listing continuing to exist.

For long-term use, move to the trademark-free SiteAtlas listing and use the SiteAtlas v2 contract. The underlying v2 response contract is the same; the listing and host header change is separate from the response field changes described below.

What to migrate

There are two independent changes:

Change	Required action
v1 response → v2 response	Update endpoint paths and response parsing for the grouped, normalized v2 contract.
Similarweb API Pro listing → SiteAtlas listing	Change the RapidAPI base URL and x-rapidapi-host to siteatlas.p.rapidapi.com to reduce listing-removal risk.

If you already use the Similarweb API Pro v2 endpoints, your response-parsing work may already be complete. You should still migrate the RapidAPI listing:

- https://similarweb-api-pro.p.rapidapi.com/site-overview?url=microsoft.com
+ https://siteatlas.p.rapidapi.com/site-overview?url=microsoft.com

- x-rapidapi-host: similarweb-api-pro.p.rapidapi.com
+ x-rapidapi-host: siteatlas.p.rapidapi.com

Keep your RapidAPI key unless RapidAPI asks you to change subscriptions or credentials. After switching, verify the HTTP status, response envelope, and one or two representative metric values in staging.

Migration at a glance

v1 legacy request	v2 request	Main response change
GET /website-overview?url=microsoft.com	GET /site-overview?url=microsoft.com	Flat/camelCase fields become grouped snake_case objects.
GET /similar-sites?url=x.com	GET /site-similar?url=x.com	sourceSite and similarSites become website and similar_sites; ranking, traffic, and image data are nested per site.
GET /country-metadata	GET /country-metadata	Hyphenated ISO keys become normalized keys under a meta envelope.

The v2 endpoint names on RapidAPI omit the /siteatlas service prefix:

Access path	Site overview	Site similar	Country metadata
Direct gateway	/siteatlas/site-overview	/siteatlas/site-similar	/siteatlas/country-metadata
SiteAtlas RapidAPI	/site-overview	/site-similar	/country-metadata

1. Change the request

Direct gateway (recommended)

Create a key in the DataBee Developer Console, then use standard Bearer authentication:

curl --request GET \
  --url 'https://api.databee.dev/siteatlas/site-overview?url=microsoft.com' \
  --header 'Authorization: Bearer YOUR_DATABEE_API_KEY'

curl --request GET \
  --url 'https://api.databee.dev/siteatlas/site-similar?url=x.com' \
  --header 'Authorization: Bearer YOUR_DATABEE_API_KEY'

SiteAtlas RapidAPI listing

Keep using RapidAPI headers, but change the host and endpoint path:

curl --request GET \
  --url 'https://siteatlas.p.rapidapi.com/site-overview?url=microsoft.com' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_DATABEE_API_KEY' \
  --header 'x-rapidapi-host: siteatlas.p.rapidapi.com' \
  --header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY'

curl --request GET \
  --url 'https://siteatlas.p.rapidapi.com/site-similar?url=x.com' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_DATABEE_API_KEY' \
  --header 'x-rapidapi-host: siteatlas.p.rapidapi.com' \
  --header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY'

Existing users can continue using the legacy RapidAPI listing while migrating. Do not start new work against similarweb-api-pro.p.rapidapi.com.

2. Migrate Website Overview

Endpoint

v1: GET https://similarweb-api-pro.p.rapidapi.com/website-overview?url=microsoft.com
v2: GET https://api.databee.dev/siteatlas/site-overview?url=microsoft.com

The v2 response uses status: "success" and groups related values under website, rankings, traffic, seo, and ai_referrals. The legacy success: true flag is not the v2 success indicator.

Field mapping

v1 field from website-overview	v2 field	Migration note
success	status	Convert true to the string value "success".
site	meta.request.url, website.domain	The requested domain is represented in request metadata and website details.
title, description	website.title, website.description	Same values, now grouped under website.
category	website.category.name	v2 also provides website.category.slug.
snapshotDate	meta.snapshot_date	v2 uses a normalized date value.
ranks.global	rankings.global.rank	Nested under rankings.
ranks.country.countryCode	rankings.country.country_code	Key is normalized to snake_case.
ranks.country.rank	rankings.country.rank	Same value.
ranks.categoryRank	rankings.category.rank	v2 also provides rankings.category.category_slug.
engagementMetrics.bounceRate	traffic.engagement.bounce_rate	Key is normalized to snake_case.
engagementMetrics.pageviewsPerVisit	traffic.engagement.pages_per_visit	Key and location change.
engagementMetrics.averageVisitDurationSeconds	traffic.engagement.average_visit_duration_seconds	Key and location change.
engagementMetrics.visits	Latest entry in traffic.history	Use the entry whose month matches the reporting period.
engagementMetrics.period	traffic.period	v1 {month, year} becomes a YYYY-MM string.
estimatedMonthlyVisits[]	traffic.history[]	date becomes month; visits remains visits.
audience.topCountries[]	traffic.geography_share[]	countryCode becomes country_code; share remains a decimal.
traffic.sources[]	traffic.sources_share	v1 array becomes a keyed object; use the v2 keys as the contract.
traffic.topKeywords[].name	seo.top_keywords[].keyword	Key is renamed.
traffic.topKeywords[].volume	seo.top_keywords[].search_volume	Key is renamed.
traffic.topKeywords[].cpc	seo.top_keywords[].cpc_usd	Key is renamed and explicitly expressed in USD.
traffic.topKeywords[].estimatedMonthlyValue	seo.top_keywords[].estimated_value_usd	Key is renamed and explicitly expressed in USD.
technical.images.favicon	website.images.favicon_url	URL field is normalized and moved.
technical.images.smartphone	website.images.screenshot_mobile_url	URL field is normalized and moved.
technical.images.desktop	website.images.screenshot_desktop_url	URL field is normalized and moved.
technical.isSmallSite	website.flags.is_small_site	Flag is grouped under website.
technical.isDataFromGoogleAnalytics	traffic.is_data_from_ga	v2 exposes the data-source flag with the traffic data.
aiAnalytics.totalAiVisits	ai_referrals.total_visits	Key and location change.
aiAnalytics.globalTrafficShare	ai_referrals.global_traffic_share	Use the decimal v2 field.
aiAnalytics.topPrompts	ai_referrals.top_prompts	Same data, new namespace.
aiAnalytics.platforms[]	ai_referrals.platforms[]	name remains; v2 adds rank, uses share, and may include monthly history.

Arrays and units that need code changes

Traffic sources

The legacy response uses display labels in an array, for example Direct, Search, Paid Referrals, Referrals, Mail, and Social. v2 uses a keyed object such as:

{
  "direct": 0.5233,
  "organic_search": 0.2511,
  "paid_search": 0.0002,
  "organic_social": 0.0916,
  "paid_social": 0.0013,
  "email": 0.0116,
  "referrals": 0.0974,
  "generative_ai": 0.0208,
  "affiliate": 0,
  "display_ads": 0.0026
}

Read known v2 keys directly instead of iterating the old source/share array. Values are decimals: 0.0208 means 2.08%.

Monthly visits

The v1 percentageChange property is not part of the canonical v2 history item. Compute it in your application when needed:

const percentageChange = previousVisits
  ? ((currentVisits - previousVisits) / previousVisits) * 100
  : null;

Percent fields

The v1 payload often returned both share and sharePercentage. v2 removes these redundant pairs in the normalized sections. For traffic geography and traffic sources, v2 shares are decimals. For AI platform data, use the v2 share value as returned and do not automatically multiply it by 100 based on the v1 sharePercentage field.

3. Migrate Similar Sites

Endpoint

v1: GET https://similarweb-api-pro.p.rapidapi.com/similar-sites?url=x.com
v2: GET https://api.databee.dev/siteatlas/site-similar?url=x.com

Field mapping

v1 field	v2 field	Migration note
success	status	Convert true to "success".
sourceSite	website	The v2 response uses the same website object shape as Site Overview.
sourceSite.site	meta.website, website.domain	site is retained in metadata and normalized to domain under website.
sourceSite.title	website.title	Same value.
sourceSite.description	website.description	Same value, moved into website.
sourceSite.category	website.category	Same value, moved into website.
sourceSite.tags	website.tags	Same concept, when returned.
sourceSite.images	website.images	Full source-site image object is retained under website.
sourceSite.totalVisits	traffic.total_visits	Source-site traffic is top-level v2 traffic data.
sourceSite.globalRank	rankings.global.rank	Ranking data is top-level for the source website.
sourceSite.topCountry, sourceSite.topCountryRank	rankings.country.country_code, rankings.country.rank	v2 also returns rankings.country.country_name when available.
sourceSite.categoryRank	rankings.category.rank	v2 also returns rankings.category.category_slug, which may be null.
similarSites	similar_sites	Envelope key is normalized.
similarSites[].site	similar_sites[].domain	site becomes domain.
similarSites[].title	similar_sites[].title	Same value.
similarSites[].description	similar_sites[].description	Same value.
similarSites[].globalRank, categoryRank, topCountry, topCountryRank	similar_sites[].rankings	Ranking fields are grouped under each similar site's rankings; country rankings also include country_name.
similarSites[].totalVisits	similar_sites[].traffic.total_visits	Traffic is grouped under each similar site's traffic object.
similarSites[].images	similar_sites[].images	Full image data is retained per similar site.

The v2 response does not currently return source_site, meta.snapshot_date, meta.total_results, similar_sites[].rank, or similar_sites[].similarity_score. Do not build an integration around those fields. The response also retains description, rankings, traffic totals, and full image objects that are absent from the old documentation example.

The Site Similar response includes meta.website and meta.data_coverage. A global rank, description, or category slug can be null, and traffic.total_visits is a number that may include decimal precision.

Current v2 response shape

This is a representative shape; values and optional fields vary by domain:

{
  "status": "success",
  "meta": {
    "request": {
      "url": "github.com"
    },
    "website": "github.com",
    "data_coverage": "complete"
  },
  "website": {
    "domain": "github.com",
    "title": "GitHub · Build and ship software on a single, collaborative platform",
    "description": "Join the world's most widely adopted, AI-powered developer platform...",
    "category": {
      "slug": "Computers_Electronics_and_Technology/Programming_and_Developer_Software",
      "name": "Computers Electronics and Technology > Programming and Developer Software"
    },
    "tags": ["ruby", "ruby on rails", "github"],
    "images": {
      "favicon_url": "https://site-images.similarcdn.com/image?url=github.com&t=2",
      "screenshot_desktop_url": "https://site-images.similarcdn.com/image?url=github.com&t=1",
      "screenshot_mobile_url": "https://site-images.similarcdn.com/image?url=github.com&t=4"
    }
  },
  "rankings": {
    "global": { "rank": null },
    "country": {
      "country_code": "US",
      "country_name": "United States of America",
      "rank": 90
    },
    "category": {
      "category_slug": "Computers_Electronics_and_Technology/Programming_and_Developer_Software",
      "rank": 4
    }
  },
  "traffic": {
    "total_visits": 513197610.36
  },
  "similar_sites": [
    {
      "domain": "stackoverflow.com",
      "title": "Newest Questions",
      "description": "Stack Overflow | The World’s Largest Online Community for Developers",
      "rankings": {
        "global": { "rank": 978 },
        "country": {
          "country_code": "US",
          "country_name": "United States of America",
          "rank": 968
        },
        "category": { "category_slug": null, "rank": 39 }
      },
      "traffic": { "total_visits": 69124392.197 },
      "images": {
        "favicon_url": "https://site-images.similarcdn.com/image?url=stackoverflow.com&t=2&h=04179ebf8566da481b023bba12856a0748752b1e4a75d1b145220282ef93f21c",
        "screenshot_desktop_url": "https://site-images.similarcdn.com/image?url=stackoverflow.com&t=1&h=04179ebf8566da481b023bba12856a0748752b1e4a75d1b145220282ef93f21c",
        "screenshot_mobile_url": "https://site-images.similarcdn.com/image?url=stackoverflow.com&t=4&h=04179ebf8566da481b023bba12856a0748752b1e4a75d1b145220282ef93f21c"
      }
    }
  ]
}

4. Migrate Country Metadata

Endpoint

v1: GET https://similarweb-api-pro.p.rapidapi.com/country-metadata
v2: GET https://api.databee.dev/siteatlas/country-metadata

The supplied v1 response contains 249 countries and uses ISO-style keys with hyphens. The v2 response keeps the same country coverage but normalizes the envelope and field names:

{
  "status": "success",
  "meta": {
    "count": 249,
    "standard": "ISO 3166-1"
  },
  "countries": [
    {
      "name": "United States",
      "alpha2": "US",
      "alpha3": "USA",
      "numeric": "840"
    }
  ]
}

v1 field	v2 field	Migration note
success	status	Convert true to "success".
countries.length	meta.count	v2 gives the count explicitly.
countries[].name	countries[].name	Unchanged.
countries[].alpha-2	countries[].alpha2	Hyphen removed.
countries[].alpha-3	countries[].alpha3	Hyphen removed.
countries[].country-code	countries[].numeric	Name is normalized; value remains a string so leading zeroes are preserved.
countries[].iso_3166-2	No canonical equivalent	Do not rely on this field in v2.
countries[].region, sub-region, and related code fields	No canonical equivalent	These are not part of the canonical v2 country item.

If your application indexes countries by the old keys, update the lookup code:

// v1
const countryCode = country['alpha-2'];
const numericCode = country['country-code'];

// v2
const countryCode = country.alpha2;
const numericCode = country.numeric;

Keep numeric as a string. Converting values such as "004" to numbers removes the leading zero and breaks ISO code lookups.

5. Recommended migration sequence

1. Add a response adapter that accepts the v1 shape and emits your application’s internal model.
2. Switch requests to the v2 path and authentication/base URL in a staging environment.
3. Update field access for the grouped snake_case response shown above.
4. Add fixtures for missing, null, and empty arrays; not every domain has every metric.
5. Compare v1 and v2 values using the returned snapshot/reporting dates. The two responses may represent different snapshots and should not be compared as real-time measurements.
6. Remove the legacy adapter after all consumers use the v2 model.

See the Site Overview, Site Similar, Country Metadata, and full API reference for the current v2 request and response contracts.