BETA

Marvin2 API Documentation

INTRODUCTION

ENDPOINTS

HISTORY

Getting Started

Welcome to our API documentation. This guide will help you get started with integrating our API into your applications.

Base URL

https://classification.relativity6.com

Request Format

All requests should be sent with the following headers:

Content-Type: application/json
x-api-key: YOUR_API_KEY

Authorization

All API requests require authentication using an API key. You can obtain your API key by contacting Relativity6.

Authentication Method

Add your API key to the request headers:

Content-Type: application/json
x-api-key: YOUR_API_KEY

Migrating from Marvin API

Authentication Change

If you're migrating from the Marvin API, you'll need to update your authentication method.

Previous Method (Marvin API)

Including the API key in the request body:

{
  "token": "YOUR_API_KEY",
  "name": "Acme Corporation",
  "state": "CA",
  ...
}

New Method

Using the x-api-key header:

// Request Headers
x-api-key: YOUR_API_KEY

// Request Body
{
  "name": "Acme Corporation",
  "state": "CA",
  ...
}

Migration Steps

Remove the "token" field from your request body
Add the x-api-key: YOUR_API_KEY header to all requests
Keep all other request parameters the same

Marvin2 Endpoint

POST

/marvin2

The Marvin2 endpoint provides backward compatibility for existing integrations while improving the accuracy of the predictions.

Full Request Example

POST https://classification.relativity6.com/marvin2
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "name": "Acme Corporation",
  "state": "CA",
  "address": "123 Main Street",
  "city": "San Francisco",
  "zip": "94105",
  "country": "US",
  "predictionType": "USA_NAICS_2022",
  "description": "A software company specializing in web and mobile applications."
}

Request Body

{
  "name": "Acme Corporation",
  "state": "CA",
  "address": "123 Main Street",
  "city": "San Francisco",
  "zip": "94105",
  "country": "US",
  "predictionType": "USA_NAICS_2022",
  "description": "A software company specializing in web and mobile applications."
}

Parameters

Parameter	Type	Required	Description
name	string	Yes	The business name
state	string	Yes	State code (e.g., CA, NY)
address	string	No	Street address
city	string	No	City name
zip	string	No	Postal code
country	string	No	Country code
predictionType	string	No	Either 'USA_NAICS_2017' or 'USA_NAICS_2022'. Defaults to 'USA_NAICS_2017'
description	string	No	Optional. Additional context about the business for improved search accuracy. Maximum 300 characters.

Advanced Parameters

predictionType

Specifies which version of the NAICS (North American Industry Classification System) code list to use for predictions.

USA_NAICS_2017:

Uses the 2017 NAICS code list (default)

USA_NAICS_2022:

Uses the 2022 NAICS code list with updated industry categories

description

An optional free-text field (up to 300 characters). Use this to provide additional business context, such as a summary of services, specialties, or other relevant information. This can help improve the accuracy of the search algorithm, especially for ambiguous business names.

Response

The response structure changes based on the predictionType parameter. The prediction object key will be either usa_naics_2017_prediction_hp or usa_naics_2022_prediction_hp.

{
  "usa_naics_2017_prediction_hp": {  // or "usa_naics_2022_prediction_hp" if predictionType is "USA_NAICS_2022"
    "prediction_a": {
      "code": "541511",
      "title": "Custom Computer Programming Services",
      "accuracy": 0.92
    },
    "prediction_b": {
      "code": "518210",
      "title": "Data Processing, Hosting, and Related Services",
      "accuracy": 0.87
    }
  },
  "keywords": ["software", "development", "web", "application"],
  "company_website": ["acmecorp.com", 0.95],
  "existence_check": {
    "exists": true,
    "evidence_exist": ["acmecorp.com", "linkedin.com/company/acme-corporation", "crunchbase.com/organization/acme-corp"]
  },
  "timestamp": "2023-06-15T14:32:25Z",
  "traceId": "1-64abc123-def456789012345678901234"
}

Response Properties

Property	Type	Description
usa_naics_2017_prediction_hp	object	Predictions with top NAICS codes (when predictionType is "USA_NAICS_2017" or not specified)
usa_naics_2022_prediction_hp	object	Predictions with top NAICS codes (when predictionType is "USA_NAICS_2022")
keywords	array	Keywords extracted from company data
company_website	array	Domain name of company website and confidence score [domain, confidence]
existence_check	object	Company existence verification
existence_check.evidence_exist	array	Array of website domains where company evidence was found
timestamp	string	ISO-8601 timestamp of the response
traceId	string	Unique trace identifier for debugging

Error Codes

Status	Description
400	Bad Request - Invalid parameters
403	Forbidden - Invalid API Key or Authentication
429	Too Many Requests - Quota exceeded or plan limit reached
500	Server Error - Something went wrong on our end

Co-Tenant Endpoint

POST

/co-tenant

The Co-Tenant endpoint provides information about businesses that share the same physical location or building. This helps identify other businesses operating at the same address.

Full Request Example

POST https://classification.relativity6.com/co-tenant
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "address": "123 Main Street",
  "city": "San Francisco",
  "state": "CA",
  "postal": "94105"
}

Request Body

{
  "address": "123 Main Street",
  "city": "San Francisco",
  "state": "CA",
  "postal": "94105"
}

Parameters

Parameter	Type	Required	Description
address	string	Yes	Street address of the location
city	string	Yes	City name
state	string	Yes	State code (e.g., CA, NY)
postal	string	Yes	Postal/ZIP code

Response

The response contains co-tenancy data, including geocoding information, structure details, and comprehensive tenant information.

{
  "geocode": {
    "lat": 35.08225579999999,
    "lng": -80.8773368
  },
  "structure": {
    "structure_polygon": "POLYGON ((-80.87688135199994 35.08437577900003))"
  },
  "tenants": [
    {
      "placekey": "zzw-224@8gf-dqc-8d9",
      "location_name": "Vans",
      "brand_name": "Vans",
      "brand_id": "SG_BRAND_336d95866bf50e8249657647cb15b68c",
      "naics_code": "448210",
      "top_category": "Shoe Stores",
      "sub_category": "Shoe Stores",
      "category_tags": "[\"Accessories\", \"Children's Clothing\", \"Hats\", \"Men's Clothing\", \"Women's Clothing\"]",
      "latitude": 35.082698,
      "longitude": -80.876984,
      "street_address": "11025 Carolina Place Pkwy Ste A25",
      "city": "Pineville",
      "region": "NC",
      "postal_code": "28134",
      "open_hours": "{ \"Mon\": [[\"11:00\", \"19:00\"]], \"Tue\": [[\"11:00\", \"19:00\"]], \"Wed\": [[\"11:00\", \"19:00\"]], \"Thu\": [[\"11:00\", \"19:00\"]], \"Fri\": [[\"11:00\", \"20:00\"]], \"Sat\": [[\"11:00\", \"20:00\"]], \"Sun\": [[\"12:00\", \"18:00\"]] }",
      "domains": "[\"vans.com\"]",
      "phone_number": "+17045448551"
    }
  ]
}

Response Properties

Property	Type	Description
geocode	object	Geocoding information for the location
geocode.lat	number	Latitude of the location
geocode.lng	number	Longitude of the location
structure	object	Structure details of the building
structure.structure_polygon	string	Polygon representation of the building structure
tenants	array	List of businesses at the location
tenants[].placekey	string	Unique place key identifier for the business
tenants[].location_name	string	Name of the business location
tenants[].brand_name	string	Brand name of the business
tenants[].brand_id	string	Unique brand identifier
tenants[].naics_code	string	NAICS classification code
tenants[].top_category	string	Primary business category
tenants[].sub_category	string	Business subcategory
tenants[].category_tags	string	JSON string of category tags
tenants[].latitude	number	Latitude of the business
tenants[].longitude	number	Longitude of the business
tenants[].street_address	string	Street address of the business
tenants[].city	string	City of the business
tenants[].region	string	State/region of the business
tenants[].postal_code	string	Postal code of the business
tenants[].open_hours	string	JSON string of business hours
tenants[].domains	string	JSON string of associated domains
tenants[].phone_number	string	Phone number of the business

Use Cases

Market Research

Understand the business ecosystem around a specific location

Competitive Analysis

Identify competitors or complementary businesses in the same building

Location Intelligence

Assess the commercial viability of a location based on existing tenants

Error Codes

Status	Description
400	Bad Request - Missing required fields (address, city, state, postal)
403	Forbidden - Invalid API Key or Authentication
502	Bad Gateway - Upstream API error
503	Service Unavailable - Configuration error
504	Gateway Timeout - Error communicating with upstream service