API Documentation

MooreMetrics Dive API Documentation

The Dive API gives your app the same recommendations, name matching, and characteristic scores that the Dive sites show their visitors. Version 2.0.0.

Base URL: https://www.mooremetrics.com/wp-json/mooremetrics/v1

Endpoints marked Key need an X-API-Key header. Get a free key or open the account dashboard to review your plan, quota, renewal, and recent activity.

On this page: Authentication, Limits, Errors, Item fields, Location filtering, Endpoints, Plans, Sites and characteristics, Changes in 2.0.

Authentication

Send your API key in the X-API-Key header with every request to an endpoint marked Key. Keep the key private; if it leaks, replace it from the account dashboard.

curl -X POST "https://www.mooremetrics.com/wp-json/mooremetrics/v1/recommend" \ -H "X-API-Key: mm_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"domain": "showdive", "items": ["Breaking Bad"]}'

Limits

Each plan has a monthly request limit and a per-minute limit (see Plans). Every response to a keyed request carries these headers:

Going over either limit returns 429 Too Many Requests; the per-minute limit also sends Retry-After (seconds).

Every keyed request that passes authentication counts toward your month, including requests that return an error such as 400 because no item matched. Requests stopped before that point do not count: an unknown site, a site that is temporarily unavailable, or a missing or invalid key.

The endpoints that need no key (/domains, /domains/{domain}/items, /domains/{domain}/characteristics) do not count toward any plan, but each visitor IP address can call them about 60 times a minute.

Errors

Errors come back as JSON with an error message, and often a code you can test for in your app:

{ "error": "API key required. Pass via X-API-Key header.", "code": "missing_key" }

Item fields

Every item in a response (a recommendation, a matched input, a catalog entry) has the same core fields:

Names are matched the way each site matches what its visitors type: capitalization, accents, and punctuation do not matter, and a close name is accepted. A name that matches nothing is reported back rather than guessed.

Location filtering

chowdive and collegedive items include coordinates and can be limited to a radius. Add latitude, longitude, and optionally radius_miles (default 50) to /recommend, /recommend-by-preferences, or /domains/{domain}/items. POST requests may also send them as "location": {"latitude": 40.7128, "longitude": -74.0060, "radius_miles": 25}.

With a location filter, /recommend follows each site's own approach when few of the closest matches are nearby, and every result says how it was found in via:

If nothing in the data is inside the radius, the list is empty and notices says so.

curl -X POST "https://www.mooremetrics.com/wp-json/mooremetrics/v1/recommend" \ -H "X-API-Key: mm_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "domain": "chowdive", "items": ["Zahav (Philadelphia, PA)"], "latitude": 40.7128, "longitude": -74.0060, "radius_miles": 25, "limit": 10 }'

{ "domain": "chowdive", "matched_inputs": [ { "input": "Zahav (Philadelphia, PA)", "matched_to": "Zahav (Philadelphia, PA)", "id": "Zahav..Philadelphia..PA.", "display_name": "Zahav", "subtitle": "Philadelphia, PA", ... } ], "unmatched_inputs": [], "count": 10, "recommendations": [ { "rank": 1, "id": "Pylos..New.York..NY.", "name": "Pylos (New York, NY)", "display_name": "Pylos", "subtitle": "New York, NY", "website": "https://pylosrestaurant.com/", "city": "New York", "state": "NY", "latitude": 40.726178, "longitude": -73.984058, "distance_miles": 1.47, "score": 0.947937, "raw_score": 59.72, "via": "direct" }, ... ], "location_filter": { "latitude": 40.7128, "longitude": -74.006, "radius_miles": 25 }}

Endpoints

curl "https://www.mooremetrics.com/wp-json/mooremetrics/v1/domains"

{ "api_version": "2.0.0", "domains": [ { "slug": "showdive", "label": "ShowDive", "entity_type": "TV Show", "site_url": "https://showdive.com/", "available": true, "characteristics": 12, "supports_location": false, "similarity": "correlation_table", "supports_correlation_lookup": true }, { "slug": "alldive", "label": "AllDive", "entity_type": "Entity (cross-domain)", "available": true, "similarity": "similarity_network", "entity_types": ["author", "podcast", "movie", "video game", "show", "game/sport"], ... }, ... ]}

curl "https://www.mooremetrics.com/wp-json/mooremetrics/v1/domains/showdive/items?search=break&limit=5"

{ "domain": "chowdive", "total": 1, "limit": 1, "offset": 0, "items": [ { "id": "Zahav..Philadelphia..PA.", "name": "Zahav (Philadelphia, PA)", "display_name": "Zahav", "subtitle": "Philadelphia, PA", "website": "https://www.zahavrestaurant.com/", "city": "Philadelphia", "state": "PA", "latitude": 39.946233, "longitude": -75.145016, "characteristics": { "overall_reputation": 2.13, "family_friendly": 0.6, "greek_influence": 4, ... } } ]}

curl "https://www.mooremetrics.com/wp-json/mooremetrics/v1/domains/fragrancedive/characteristics"

{ "domain": "fragrancedive", "label": "FragranceDive", "entity_type": "Fragrance", "available": true, "supports_location": false, "characteristics": [ { "key": "mainstream", "label": "Mainstream", "short_label": "Mainstream", "description": "Widely sold and widely worn, versus niche.", "low_label": "Niche", "high_label": "Mainstream", "default_on": true, "range": { "min": -4, "max": 4 } }, ... ]}

curl -X POST "https://www.mooremetrics.com/wp-json/mooremetrics/v1/recommend" \ -H "X-API-Key: mm_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "domain": "showdive", "items": ["Breaking Bad", "The Wire"], "limit": 10, "include_characteristics": true }'

{ "domain": "showdive", "matched_inputs": [ { "input": "Breaking Bad", "matched_to": "Breaking Bad", "id": "Breaking.Bad", "name": "Breaking Bad", "display_name": "Breaking Bad", "subtitle": "", "website": "https://en.wikipedia.org/wiki/Breaking_Bad" }, ... ], "unmatched_inputs": [], "scoring": { "method": "Sum of the stored similarity values between each candidate and your inputs, the same query the ShowDive site runs.", "score": "raw_score / (number of matched inputs x largest value in the similarity table); higher is more similar.", "scale_max": 63, "direction": "higher_is_better" }, "count": 10, "recommendations": [ { "rank": 1, "id": "The.Shield", "name": "The Shield", "display_name": "The Shield", "subtitle": "", "website": "https://en.wikipedia.org/wiki/The_Shield", "score": 0.807857, "raw_score": 101.79, "characteristics": { "critical_acclaim": 3.46, "child_suitability": -3.13, "crime_focus": 3.92, ... } }, ... ]}

curl -X POST "https://www.mooremetrics.com/wp-json/mooremetrics/v1/recommend" \ -H "X-API-Key: mm_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"domain": "alldive", "items": ["Breaking Bad (show)"], "entity_types": ["movie", "podcast"]}'

curl -X POST "https://www.mooremetrics.com/wp-json/mooremetrics/v1/recommend-by-preferences" \ -H "X-API-Key: mm_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "domain": "fragrancedive", "preferences": { "mainstream": -2.0, "intense_powerful": 3.0, "expensive": 2.5 }, "limit": 10 }'

{ "domain": "fragrancedive", "preferences_used": { "mainstream": -2, "intense_powerful": 3, "expensive": 2.5 }, "scoring": { "method": "Mean squared difference between each item's scores and your targets over the characteristics you sent, as on the FragranceDive site.", "distance_score": "lower is better (0 = exact match)", "fit": "0-100, the closeness shown on the site's result cards: 100 x (1 - sqrt(distance_score) / 8)" }, "count": 10, "recommendations": [ { "rank": 1, "id": "Gucci.Nobile..Gucci.", "name": "Gucci Nobile (Gucci)", "display_name": "Gucci Nobile", "subtitle": "Gucci", "website": "https://www.fragrantica.com/perfume/Gucci/Gucci-Nobile-689.html", "fit": 97, "distance_score": 0.068967 }, ... ]}

curl -X POST "https://www.mooremetrics.com/wp-json/mooremetrics/v1/recommend-by-preferences" \ -H "X-API-Key: mm_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "domain": "collegedive", "preferences": { "Prestige": 2.0, "Urbanicity": 1.5 }, "latitude": 42.3601, "longitude": -71.0589, "radius_miles": 100, "limit": 10 }'

curl -H "X-API-Key: mm_live_your_key_here" \ "https://www.mooremetrics.com/wp-json/mooremetrics/v1/correlation?domain=moviedive&item1=The+Godfather&item2=The+Godfather+Part+II"

{ "domain": "moviedive", "item1": { "id": "The.Godfather", "name": "The Godfather", "display_name": "The Godfather", "subtitle": "", "website": "https://en.wikipedia.org/wiki/The_Godfather" }, "item2": { "id": "The.Godfather.Part.II", "name": "The Godfather Part II", "display_name": "The Godfather Part II", "subtitle": "", "website": "https://en.wikipedia.org/wiki/The_Godfather_Part_II" }, "correlation": 0.752456, "raw_value": 35.67, "scale_max": 63, "scale": "correlation = square root of (raw_value / scale_max), where scale_max is the largest value in the MovieDive similarity table. ..."}

curl -H "X-API-Key: mm_live_your_key_here" "https://www.mooremetrics.com/wp-json/mooremetrics/v1/usage"

{ "plan": "basic", "requests_this_month": 881, "monthly_limit": 5000, "remaining": 4119, "resets_on": "2026-11-01", "breakdown": [ { "domain": "chowdive", "endpoint": "recommend", "count": 42 }, ... ]}

curl -X POST "https://www.mooremetrics.com/wp-json/mooremetrics/v1/register" \ -H "Content-Type: application/json" \ -d '{"email": "you@example.com"}'

The account dashboard uses two more endpoints, POST /account/summary and POST /account/rotate-key. Both take your email and key in the request body, use no quota, and work only from this site's own pages.

Plans

Upgrade your plan

Sites and characteristics

Use the slug as domain. Open a site to see its characteristic keys, in the order its sliders show them, with the meaning of each end of the -4 to 4 scale.

Changes in version 2.0

• Results now come from each site's own engine, so they match what the site shows for the same input, and they follow each site's updates automatically.
• New sites: gundive and alldive (with the entity_types and diversify options).
• Every item has display_name, subtitle, and website. Use id to send an exact item back.
• score on /recommend is now on a fixed 0 to 1 scale (see that endpoint), and raw_score holds the site's own value. Before 2.0, score added up the square roots of each value divided by the table's largest value.
• correlation is calculated as before (the square root of the stored value divided by the table's largest value) and now comes with raw_value and scale_max.
• /recommend-by-preferences results have fit (0 to 100) next to distance_score.
• Characteristic keys follow the sites. Keys that were renamed still work, with a warning; keys a site retired are ignored, with a warning.
• A site whose data is temporarily unavailable answers 503 instead of wrong or empty results, and that does not count toward your month.

Support

Questions or issues? Contact reductionist@gmail.com.