Localranker API

// Include in every request
headers: {
  "x-api-key": "sk_live_your_api_key"
}

{
  "mcpServers": {
    "localranker": {
      "url": "https://mcp.localranker.fr/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key"
      }
    }
  }
}

{
  "success": false,
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "type": "field",
      "msg": "locationId must be a positive integer",
      "path": "locationId",
      "location": "query"
    }
  ],
  "errors": [ /* same as details */ ]
}

{
  "success": false,
  "error": "No api key provided",
  "code": "MISSING_API_KEY"
}

{
  "success": false,
  "error": "API credit exceeded",
  "code": "API_CREDITS_EXCEEDED"
}

{
  "success": false,
  "error": "Too many requests from this IP. Max: 100/min - Please try again after 1 minute.",
  "code": "RATE_LIMIT_EXCEEDED"
}

{
  "success": false,
  "message": "All photos failed validation",
  "error": "All photos failed validation",
  "code": "MEDIA_UPLOAD_FAILED",
  "results": [
    {
      "url": "https://example.com/photo.jpg",
      "status": "validation_error",
      "error": "Image too small"
    }
  ]
}

const response = await fetch("https://developers.localranker.fr/v1/locations?page=1", {
  headers: { "x-api-key": "sk_live_your_api_key" }
});
const data = await response.json();

{
  "locations": [
    {
      "placeID": "ChIJh5ixZOZz5kcRtmuVD2mF07w",
      "locationID": 102,
      "locationName": "Localranker",
      "locationAddress": "15 Rue des Halles, Paris, 75001"
    }
  ],
  "nextPage": "https://developers.localranker.fr/v1/locations?page=2",
  "totalItems": 150,
  "totalPages": 2
}

const response = await fetch("https://developers.localranker.fr/v1/locations/opening-hours?locationId=102", {
  headers: { "x-api-key": "sk_live_your_api_key" }
});
const data = await response.json();

{
  "locationId": 102,
  "hours": [
    {
      "openDay": "MONDAY",
      "openTime": { "hours": 9 },
      "closeDay": "MONDAY",
      "closeTime": { "hours": 18 }
    },
    {
      "openDay": "TUESDAY",
      "openTime": { "hours": 9 },
      "closeDay": "TUESDAY",
      "closeTime": { "hours": 18 }
    }
  ]
}

const response = await fetch("https://developers.localranker.fr/v1/locations/location?placeId=ChIJh5ixZOZz5kcRtmuVD2mF07w", {
  headers: { "x-api-key": "sk_live_your_api_key" }
});
const data = await response.json();

{
  "title": "Localranker",
  "languageCode": "fr",
  "phoneNumbers": {},
  "categories": {
    "primaryCategory": {
      "name": "categories/gcid:internet_marketing_service",
      "displayName": "Service de marketing Internet"
    }
  },
  "storefrontAddress": {
    "addressLines": ["15 Rue des Halles"],
    "locality": "Paris",
    "postalCode": "75001",
    "regionCode": "FR"
  },
  "websiteUri": "https://localranker.fr",
  "regularHours": { /* ... */ },
  "profile": {
    "description": "LocalRanker est une plateforme..."
  }
}

const response = await fetch("https://developers.localranker.fr/v1/locations/location", {
  method: "POST",
  headers: {
    "x-api-key": "sk_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    isGoogle: true,
    isTestingMode: true,
    gbpAccountId: "123456789",
    location: {
      title: "My New Location",
      storefrontAddress: {
        addressLines: ["12 rue de la paix"],
        locality: "Paris",
        postalCode: "75001",
        regionCode: "FR"
      },
      categories: {
        primaryCategory: {
          name: "categories/gcid:internet_marketing_service"
        }
      }
    }
  })
});

{
  "success": true,
  "data": {
    "message": "TEST MODE - Request format is valid. Nothing was saved or sent to Google",
    "requestId": "d08c141b-15d3-44ad-...",
    "gbpAccountId": "123456789"
  }
}

const response = await fetch("https://developers.localranker.fr/v1/locations/media", {
  method: "POST",
  headers: {
    "x-api-key": "sk_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    locationId: 102,
    photos: [
      { url: "https://example.com/photo1.jpg", category: "EXTERIOR" },
      { url: "https://example.com/photo2.jpg", category: "INTERIOR" }
    ]
  })
});

{
  "success": true,
  "message": "All photos uploaded successfully",
  "results": [
    { "url": "https://example.com/photo1.jpg", "status": "success" },
    { "url": "https://example.com/photo2.jpg", "status": "success" }
  ]
}

// See Errors — MEDIA_UPLOAD_FAILED; message + results preserved

const response = await fetch("https://developers.localranker.fr/v1/locations/location", {
  method: "PUT",
  headers: {
    "x-api-key": "sk_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    locationId: 102,
    isTestingMode: false,
    location: {
      title: "Updated Location Name",
      websiteUri: "https://newwebsite.fr"
    }
  })
});

const response = await fetch("https://developers.localranker.fr/v1/locations/location", {
  method: "PUT",
  headers: {
    "x-api-key": "sk_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    locationId: 102,
    // true checks the format only; set false to apply
    isTestingMode: true,
    location: {
      storefrontAddress: {
        regionCode: "FR",
        addressLines: ["20 rue de Rivoli"],
        locality: "Paris",
        postalCode: "75004"
      }
    }
  })
});

const response = await fetch("https://developers.localranker.fr/v1/locations/location", {
  method: "PUT",
  headers: {
    "x-api-key": "sk_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    locationId: 102,
    isTestingMode: false,
    attributes: {
      socials: [
        { type: "url_instagram", url: "https://instagram.com/mybusiness" },
        { type: "url_facebook", url: "https://facebook.com/mybusiness" }
      ]
    }
  })
});

{
  "message": "Request received and is processing",
  "requestId": 42
}

const response = await fetch("https://developers.localranker.fr/v1/locations/location/update?requestId=42", {
  headers: { "x-api-key": "sk_live_your_api_key" }
});
const data = await response.json();

{
  "requestId": 42,
  "locationId": 102,
  "status": "partially_applied",
  "createdAt": "2026-10-28T08:18:35.000Z",
  "skippedFields": [
    {
      "field": "phoneNumbers",
      "reason": "refused",
      "detail": "Invalid phone number"
    }
  ]
}

const response = await fetch("https://developers.localranker.fr/v1/publications?locationId=102", {
  headers: { "x-api-key": "sk_live_your_api_key" }
});
const data = await response.json();

{
  "posts": [
    {
      "title": "New blog post about local SEO",
      "content": "Discover our latest tips...",
      "imageUrl": "https://...",
      "publishedAt": "2025-03-01T10:00:00.000Z"
    }
  ],
  "totalPostsReturned": 1
}

const url = "https://developers.localranker.fr/v1/stats"
  + "?locationsIds=all&startDate=2025-01-01&endDate=2025-03-01&interval=month";

const response = await fetch(url, {
  headers: { "x-api-key": "sk_live_your_api_key" }
});
const data = await response.json();

{
  "reviews": {
    "reviews_count": 87,
    "nbReplied": 72,
    "responseRate": 83,
    "averageRate": 4.52
  },
  "report": { /* GBP performance stats */ }
}

const url = "https://developers.localranker.fr/v1/stats/gbp-keywords"
  + "?locationsIds=all&startDate=2025-01-01&endDate=2025-03-01&groupBy=account";

const response = await fetch(url, {
  headers: { "x-api-key": "sk_live_your_api_key" }
});
const data = await response.json();

{
  "groupBy": "account",
  "searchKeywords": {
    "topKeywords": [
      { "keyword": "plombier paris", "impressions": 842, "isThreshold": false }
    ],
    "totalImpressions": 12500,
    "uniqueKeywords": 87,
    "monthlyTotals": [
      { "month": "2025-01", "impressions": 4100 }
    ]
  }
}

{
  "groupBy": "location",
  "locations": [
    {
      "locationId": 102,
      "searchKeywords": { /* same shape as account.searchKeywords */ }
    }
  ]
}

const url = "https://developers.localranker.fr/v1/local-audit"
  + "?locationsIds=102&lang=all&includeHistory=true";

const response = await fetch(url, {
  headers: { "x-api-key": "sk_live_your_api_key" }
});
const data = await response.json();

{
  "lang": "all",
  "locations": [
    {
      "locationId": 102,
      "placeId": "ChIJ...",
      "localScore": 78,
      "validCount": 22,
      "invalidCount": 8,
      "auditedAt": "2026-06-20T03:00:00.000Z",
      "audited": true,
      "issuesSummary": { "critical": 2, "medium": 4, "low": 2 },
      "validSummary": { "critical": 6, "medium": 12, "low": 4 },
      "issues": {
        "critical": [
          {
            "code": "no-website",
            "status": "issue",
            "criticality": "critical",
            "type": "basic-info",
            "labels": {
              "fr": { "header": "Aucun site web renseigné", "content": "...", "fix": "..." },
              "en": { "header": "No website filled in", "content": "...", "fix": "..." }
            }
          }
        ],
        "medium": [],
        "low": []
      },
      "valid": { /* same item shape, grouped by criticality */ },
      "localScoreHistory": [
        { "month": "2025-07", "localScore": 70 },
        { "month": "2025-08", "localScore": 74 },
        { "month": "2025-09", "localScore": null }
      ]
    }
  ]
}

const url = "https://developers.localranker.fr/v1/positions/overview"
  + "?locationsIds=all&startDate=2026-01-01&endDate=2026-03-31&engine=both";

const response = await fetch(url, {
  headers: { "x-api-key": "sk_live_your_api_key" }
});

{
  "period": { "startDate": "2026-01-01", "endDate": "2026-03-31" },
  "meta": {
    "totalKeywordsTracked": 1482,
    "locationsCount": 86,
    "status": "fresh",
    "crawlFrequency": "monthly",
    "kpiSource": "timeline",
    "months": ["2026-01", "2026-02", "2026-03"]
  },
  "localPack": { "recent": 37, "start": 52, "evo": -15 },
  "search": {
    "visibility": { "recent": 41, "start": 35, "evo": 6 },
    "coverage": { "recent": 72, "start": 68, "evo": 4 },
    "avgPosition": { "recent": 7.4, "start": 8.1, "evo": 0.7 },
    "rankingDistribution": {
      "recent": { "top3": 210, "fourToTen": 480, "elevenToTwenty": 377, "notRanking": 415, "total": 1482 },
      "start": { "top3": 190, "fourToTen": 450, "elevenToTwenty": 360, "notRanking": 482, "total": 1482 }
    },
    "sample": { "rows": 1482, "measured": 1410, "paired": 1388 }
  },
  "maps": { "visibility": { "recent": 46, "start": 35, "evo": 11 } },
  "timeline": [
    { "month": "2026-01", "search": { "visibility": 35, "coverage": 68, "avgPosition": 8.1 }, "maps": { "visibility": 35 } }
  ]
}

const url = "https://developers.localranker.fr/v1/positions/keywords"
  + "?locationsIds=all&startDate=2026-01-01&endDate=2026-03-31&groupCities=true&limit=50";

{
  "period": { "startDate": "2026-01-01", "endDate": "2026-03-31" },
  "meta": { "groupCities": true, "status": "fresh", "crawlFrequency": "monthly" },
  "keywords": [
    {
      "keywordId": null,
      "keywordIds": [12, 18],
      "keyword": "vitrier {{city}}",
      "isCityGroup": true,
      "keywordBase": "vitrier",
      "volume": 1300,
      "tags": ["urgence"],
      "locationsCount": 12,
      "cities": ["Lyon", "Villeurbanne"],
      "citiesCount": 2,
      "variantCount": 2,
      "variants": [
        { "keyword": "vitrier lyon", "keywordIds": [12], "city": "Lyon" }
      ],
      "variantsTruncated": false,
      "search": {
        "visibility": { "recent": 41, "start": 35, "pairedRecent": 41, "evo": 6 },
        "coverage": { "recent": 83, "start": 79, "pairedRecent": 83, "evo": 4 },
        "avgPosition": { "recent": 4.2, "start": null, "evo": 1 },
        "localPackPosition": 1.8,
        "rankedUrl": "https://example.fr/lyon"
      },
      "maps": {
        "visibility": { "recent": 62, "start": 50, "pairedRecent": 62, "evo": 12 },
        "coverage": { "recent": 100, "start": 92, "pairedRecent": 100, "evo": 8 },
        "avgPosition": { "recent": 3.1, "start": null, "evo": 1 }
      }
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 210, "totalPages": 5, "hasNext": true }
}

const url = "https://developers.localranker.fr/v1/positions/locations"
  + "?locationsIds=all&startDate=2026-01-01&endDate=2026-03-31&page=1&limit=50";

{
  "period": { "startDate": "2026-01-01", "endDate": "2026-03-31" },
  "meta": { "status": "fresh", "kpiSource": "timeline", "crawlFrequency": "monthly" },
  "locations": [
    {
      "locationId": 102,
      "name": "Vitrier Lyon",
      "city": "Lyon",
      "postalCode": "69001",
      "department": "69",
      "keywordsTracked": 18,
      "search": {
        "visibility": { "recent": 41, "start": 35, "evo": 6 },
        "coverage": { "recent": 72, "start": 68, "evo": 4 },
        "avgPosition": { "recent": 7.4, "start": 8.1, "evo": 0.7 },
        "keywordsGained": 3,
        "keywordsLost": 1,
        "localPack": { "inPack": 4, "available": 9, "sharePct": 44 }
      },
      "maps": {
        "visibility": { "recent": 58, "start": 50, "evo": 8 }
      }
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 86, "totalPages": 2, "hasNext": true }
}

const url = "https://developers.localranker.fr/v1/positions/locations"
  + "?locationsIds=all&startDate=2026-01-01&endDate=2026-03-31&keywordId=4821&engine=search";

{
  "locations": [
    {
      "locationId": 102,
      "name": "Vitrier Lyon",
      "keywordId": 4821,
      "keyword": "vitrier lyon",
      "keywordsTracked": 1,
      "search": {
        "lastPosition": 3,
        "previous": 5,
        "delta": 2,
        "visibility": 68,
        "url": "https://example.fr/lyon",
        "hasLocalPack": true,
        "localPackPosition": 2
      }
    }
  ]
}

const url = "https://developers.localranker.fr/v1/positions/serps"
  + "?locationsIds=102&keywordId=4821&engine=search"
  + "&startDate=2026-01-01&endDate=2026-03-31";

{
  "keywordId": 4821,
  "engine": "search",
  "locationId": 102,
  "period": { "startDate": "2026-01-01", "endDate": "2026-03-31" },
  "anchors": ["2026-01-31", "2026-02-28", "2026-03-31"],
  "snapshot": {
    "crawledAt": "2026-03-30T08:12:00.000Z",
    "serpId": "3e1f37e1-bdec-43b9-9f12-a803a8972f7c",
    "yourPosition": 3,
    "hasLocalPack": true,
    "ads": { "count": 2, "domains": ["ads.fr"] },
    "organicResults": [
      { "position": 1, "isYou": false, "title": "Concurrent", "url": "https://concurrent.fr", "domain": "concurrent.fr" },
      { "position": 3, "isYou": true, "delta": 2, "title": "Vitrier Lyon", "url": "https://example.fr/lyon", "domain": "example.fr" }
    ],
    "localPack": [
      { "position": 1, "title": "Autre", "website": "https://autre.fr", "ludocid": "999", "isYou": false },
      { "position": 2, "title": "Vitrier Lyon", "isYou": true }
    ]
  },
  "startSnapshot": { "yourPosition": 5, "serpId": "…" },
  "rankingEvo": [
    { "anchor": "2026-01-31", "crawledAt": "2026-01-29T10:00:00.000Z", "serpId": "…", "position": 5 },
    { "anchor": "2026-03-31", "position": 3 }
  ]
}

{
  "position": 2,
  "isYou": true,
  "name": "Vitrier Lyon",
  "ludocid": "111",
  "rating": 4.8,
  "reviews": 175,
  "address": "1 rue, Lyon",
  "category": "Vitrier"
}

const url = "https://developers.localranker.fr/v1/positions/competitors"
  + "?locationsIds=all&startDate=2026-01-01&endDate=2026-03-31"
  + "&engine=search&groupId=1229&limit=50";

{
  "view": "national",
  "engine": "search",
  "meta": {
    "status": "fresh",
    "keywordScope": { "total": 1883, "compared": 1883 },
    "period": { "startDate": "2026-01-01", "endDate": "2026-03-31", "hasEvolution": true }
  },
  "activeBrand": { "groupID": 1229, "displayName": "Domaliance", "searchDomain": "domaliance.fr" },
  "you": {
    "label": "Domaliance",
    "domain": "domaliance.fr",
    "avgPosition": 9,
    "avgVisibility": 11,
    "coveragePct": 32,
    "top3Pct": 5,
    "top10Pct": 19,
    "keywordsLost": 1286,
    "evo": { "avgVisibility": { "from": 9, "to": 11 } }
  },
  "pinned": [
    {
      "id": 172,
      "name": "O2",
      "domain": "o2.fr",
      "avgPosition": 8,
      "avgVisibility": 24,
      "coveragePct": 57,
      "top3Pct": 13,
      "beatsYouCount": 209,
      "youWinCount": 1378
    }
  ],
  "discovered": [
    { "id": "destia.fr", "domain": "destia.fr", "keywordsCovered": 1324, "avgVisibility": 29 }
  ],
  "comparison": [
    {
      "keywordId": 34717,
      "locationId": 7991,
      "keyword": "femme de menage boulogne-billancourt",
      "you": { "position": 18, "visibility": 8, "notRanking": false },
      "youStart": { "position": 17, "visibility": 9, "notRanking": false },
      "competitors": [
        { "pinnedId": 172, "name": "O2", "position": 3, "visibility": 68, "notRanking": false }
      ],
      "gapVsFirst": -15
    }
  ],
  "battleground": { "departments": [{ "departmentCode": "92" }] },
  "visibilityTimeline": [
    { "month": "2026-01", "you": 7, "youCoverage": 20 }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1883, "hasNext": true }
}

const url = "https://developers.localranker.fr/v1/positions/competitors"
  + "?locationsIds=7989&startDate=2026-01-01&endDate=2026-03-31&engine=maps";

{
  "view": "local",
  "you": {
    "label": "Azaé Paris 17",
    "ludocid": "5216821773721868648",
    "avgVisibility": 0,
    "reputation": { "avgRating": 4.8, "avgReviews": 175, "source": "location" }
  },
  "pinned": [
    { "id": "1073255969081445980", "name": "Shiva Paris 4ème", "ludocid": "1073255969081445980", "top3Pct": 42 }
  ],
  "discovered": [
    { "id": "9046502819007059214", "displayName": "Azaé Paris 14", "keywordsCovered": 7 }
  ],
  "topMapsCategories": [{ "category": "Service de ménage" }]
}

const response = await fetch("https://developers.localranker.fr/v1/reviews?locationId=102&limit=20", {
  headers: { "x-api-key": "sk_live_your_api_key" }
});
const data = await response.json();

const url = "https://developers.localranker.fr/v1/reviews"
  + "?platform=google&minRating=4&startDate=2025-01-01&endDate=2025-12-31"
  + "&sortBy=rating&sortOrder=desc&includeAnswer=false";

const response = await fetch(url, {
  headers: { "x-api-key": "sk_live_your_api_key" }
});

{
  "reviews": [
    {
      "reviewId": "AbCdEf123...",
      "platform": "google",
      "author": "Jean Dupont",
      "authorPhoto": "https://lh3.googleusercontent.com/...",
      "rating": 5,
      "content": "Excellent service, highly recommended!",
      "reviewDate": "2025-06-15T00:00:00.000Z",
      "mediaUrls": [],
      "locationName": "Localranker",
      "locationAddress": "15 Rue des Halles, Paris, 75001",
      "placeId": "ChIJh5ixZOZz5kcRtmuVD2mF07w",
      "locationId": 102,
      "ownerAnswer": "Merci beaucoup Jean!",
      "ownerAnswerDate": "2025-06-16T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 150,
    "totalPages": 8,
    "nextPage": "https://developers.localranker.fr/v1/reviews?page=2&limit=20"
  }
}

const url = "https://developers.localranker.fr/v1/reviews/by-location"
  + "?startDate=2026-04-19&endDate=2026-10-19&maxReviews=0";

const response = await fetch(url, {
  headers: { "x-api-key": "sk_live_your_api_key" }
});

{
  "platform": "google",
  "period": { "startDate": "2026-04-19", "endDate": "2026-10-19" },
  "summary": {
    "locations": 120,
    "locationsWithoutReviews": 7,
    "totalReviews": 1840,
    "avgRating": 4.62
  },
  "locations": [
    {
      "locationId": 102,
      "placeId": "ChIJh5ixZOZz5kcRtmuVD2mF07w",
      "locationName": "Localranker",
      "locationAddress": "15 Rue des Halles, Paris, 75001",
      "reviewsCount": 0,
      "avgRating": null,
      "nbReplied": 0,
      "responseRate": null,
      "lastReviewDate": "2025-12-03"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "totalItems": 7,
    "totalPages": 1
  }
}