Référence de l'API

points de terminaison

POSTCréer une analyse d'achat POSTCréer une analyse d'arbitrage POSTCréer une analyse personnelle POSTCréer une analyse Cohost

RESSOURCES

Premiers pas Authentification Codes d'erreur

Documentation de l'API

Bienvenue sur l'API BNBCalc. Cette documentation vous aidera à intégrer nos outils d'analyse immobilière dans votre application.

Notre API RESTful offre un accès programmatique aux données complètes des locations de courte durée de BNBCalc, aux estimations de revenus des biens, à l'analyse du marché et aux projections d'investissement. Que vous développiez un logiciel de gestion immobilière, des plateformes immobilières ou des outils d'analyse d'investissement, notre API fournit les données dont vous avez besoin.

Premiers pas

Pour commencer à utiliser l'API BNBCalc, vous devrez:

1. Créez un compte BNBCalc ou connectez-vous à votre compte existant

2. Accédez aux paramètres de votre compte pour générer une clé API

3. Incluez votre clé API dans toutes les requêtes API en utilisant l'en-tête x-bnbcalc-api-key.

4. Commencez à faire des demandes pour accéder aux données et analyses immobilières.

Tous les points d'accès de l'API utilisent HTTPS et renvoient des réponses au format JSON. Notre API suit les principes RESTful et utilise les codes de réponse HTTP standard pour indiquer le succès ou l'échec.

Authentification

Toutes les requêtes API nécessitent une authentification à l'aide d'une clé API. Les clés API sont associées à votre compte BNBCalc et doivent être gardées en sécurité. Incluez votre clé API dans l'en-tête de la requête comme indiqué ci-dessous:

x-bnbcalc-api-key: YOUR_API_KEY

Vous pouvez générer des clés API à partir de la page de paramètres de votre compte. Incluez l'en-tête x-bnbcalc-api-key dans chaque requête API pour vous authentifier.

POST/v1/external/analysis/create/buy

Créer une analyse d'achat

Créer une nouvelle analyse d'achat pour une propriété. Nécessite des détails sur la propriété, des informations sur l'emplacement et le prix d'achat.

Paramètres de Localisation (Conditionnel)

⚠️ Fournissez soit lat ET lng, soit fullAddress. Au moins une méthode est requise.

latnumberconditionnel

Coordonnée de latitude (doit être fournie avec lng si fullAddress n'est pas utilisée)(e.g., 27.7676)

lngnumberconditionnel

Coordonnée de longitude (doit être fournie avec lat si fullAddress n'est pas utilisée)(e.g., -82.6403)

fullAddressstringconditionnel

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Paramètres Requis

purchasePriceUSDnumberobligatoire

Prix d'achat en USD(e.g., 350000)

bedroomsnumberobligatoire

Nombre de chambres(e.g., 3)

bathroomsnumberobligatoire

Nombre de salles de bains(e.g., 2)

accomodatesnumberobligatoire

Nombre d'invités que la propriété peut accueillir(e.g., 6)

Paramètres Optionnels

monthlyRentUSDnumberoptionnel

Loyer mensuel attendu en USD pour une location à long terme(e.g., 2500)

interestRatePercentagenumberoptionnel

Pourcentage du taux d'intérêt (0-15)(e.g., 5.1)

squareFeetnumberoptionnel

Surface en pieds carrés de la propriété(e.g., 1500)

statestringoptionnel

Nom de l'État(e.g., Florida)

citystringoptionnel

Nom de la ville(e.g., St. Petersburg)

countystringoptionnel

Nom du comté(e.g., Pinellas County)

postalCodestringoptionnel

Code postal(e.g., 33703)

countrystringoptionnel

Nom du pays(e.g., United States)

streetstringoptionnel

Nom de la rue(e.g., 2nd Avenue North)

streetNumberstringoptionnel

Numéro de rue(e.g., 4935)

unitstringoptionnel

Numéro d'unité/appartement, le cas échéant

Demande d'exemple

curl -X POST \
  https://atlas.bnbcalc.com/v1/external/analysis/create/buy \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 400000
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/buy',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 400000
})
  }
);
const data = await response.json();

import requests

data = {
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 400000
}

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/analysis/create/buy',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

Réponse d'exemple

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
    "type": "Point",
    "coordinates": [-82.6403, 27.7676],
    "comparables": ["..."],
    "downPaymentPercentage": 20,
    "mortgageLength": 30,
    "yearsRemainingOnMortgage": 30,
    "interestRatePercentage": 4,
    "propertyTaxPercentage": 0.75,
    "monthlyRevenueUSD": 5328.730331803278,
    "monthlyExpensesUSD": 1474.1603364983607,
    "monthlyTaxesUSD": 250,
    "yearOneRevenueUSD": 63944.76398163934,
    "yearOneOperatingIncomeUSD": 46254.83994365901,
    "yearOneMorgageAndTaxesUSD": 21324,
    "yearOneCashFlowUSD": 24930.83994365901,
    "yearOneCashOnCashPercentage": 24.86817214984141,
    "yearOneCapRatePercentage": 11.563709985914752,
    "yearOneReturnOnInvestmentPercentage": 63.78402823049849,
    "yearOnePrincipalPaydownUSD": 85635.31658640636,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10,
  }
}

POST/v1/external/create/arb

Créer une analyse d'arbitrage

Créez une nouvelle analyse d'arbitrage (arbitrage locatif) pour un bien immobilier. Utilise les mêmes champs obligatoires que l'analyse d'achat.

Paramètres de Localisation (Conditionnel)

⚠️ Fournissez soit lat ET lng, soit fullAddress. Au moins une méthode est requise.

latnumberconditionnel

Coordonnée de latitude (doit être fournie avec lng si fullAddress n'est pas utilisée)(e.g., 27.7676)

lngnumberconditionnel

Coordonnée de longitude (doit être fournie avec lat si fullAddress n'est pas utilisée)(e.g., -82.6403)

fullAddressstringconditionnel

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Paramètres Requis

monthlyRentUSDnumberobligatoire

Loyer mensuel attendu en USD pour une location à long terme(e.g., 2500)

bedroomsnumberobligatoire

Nombre de chambres(e.g., 3)

bathroomsnumberobligatoire

Nombre de salles de bains(e.g., 2)

accomodatesnumberobligatoire

Nombre d'invités que la propriété peut accueillir(e.g., 6)

Paramètres Optionnels

purchasePriceUSDnumberoptionnel

Prix d'achat en USD(e.g., 350000)

squareFeetnumberoptionnel

Surface en pieds carrés de la propriété(e.g., 1500)

statestringoptionnel

Nom de l'État(e.g., Florida)

citystringoptionnel

Nom de la ville(e.g., St. Petersburg)

countystringoptionnel

Nom du comté(e.g., Pinellas County)

postalCodestringoptionnel

Code postal(e.g., 33703)

countrystringoptionnel

Nom du pays(e.g., United States)

streetstringoptionnel

Nom de la rue(e.g., 2nd Avenue North)

streetNumberstringoptionnel

Numéro de rue(e.g., 4935)

unitstringoptionnel

Numéro d'unité/appartement, le cas échéant

Demande d'exemple

curl -X POST \
  https://atlas.bnbcalc.com/v1/external/create/arb \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/create/arb',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
})
  }
);
const data = await response.json();

import requests

data = {
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "monthlyRentUSD": 2000
}

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/create/arb',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

Réponse d'exemple

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
    "type": "Point",
    "coordinates": [-82.6403, 27.7676],
    "comparables": ["..."],,
    "monthlyRentUSD": 2000,
    "yearOneRentUSD": 24000,
    "monthlyRevenueUSD": 13432.825977452352,
    "monthlyExpensesUSD": 2263.6108575197586,
    "yearOneRevenueUSD": 161193.91172942822,
    "yearOneOperatingIncomeUSD": 134030.58143919113,
    "yearOneCashFlowUSD": 110030.58143919116,
    "yearOneCashOnCashPercentage": 1317.415965507557,
    "totalCashInvestment": 8352,
  }
}

POST/v1/external/analysis/create/owned

Créer une analyse personnelle

Créer une nouvelle analyse pour un bien immobilier détenu. Utilise les mêmes champs obligatoires que l'analyse d'achat.

Paramètres de Localisation (Conditionnel)

⚠️ Fournissez soit lat ET lng, soit fullAddress. Au moins une méthode est requise.

latnumberconditionnel

Coordonnée de latitude (doit être fournie avec lng si fullAddress n'est pas utilisée)(e.g., 27.7676)

lngnumberconditionnel

Coordonnée de longitude (doit être fournie avec lat si fullAddress n'est pas utilisée)(e.g., -82.6403)

fullAddressstringconditionnel

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Paramètres Requis

purchasePriceUSDnumberobligatoire

Prix d'achat en USD(e.g., 350000)

downPaymentPercentagenumberobligatoire

Pourcentage de paiement initial (0-40)(e.g., 20)

interestRatePercentagenumberobligatoire

Pourcentage du taux d'intérêt (0-15)(e.g., 5.1)

mortgageLengthnumberobligatoire

Durée du prêt hypothécaire en années (0-30)(e.g., 30)

yearsRemainingOnMortgagenumberobligatoire

Années restantes sur l'hypothèque (Ne peut pas dépasser la durée de l'hypothèque)

bedroomsnumberobligatoire

Nombre de chambres(e.g., 3)

bathroomsnumberobligatoire

Nombre de salles de bains(e.g., 2)

accomodatesnumberobligatoire

Nombre d'invités que la propriété peut accueillir(e.g., 6)

Paramètres Optionnels

monthlyRentUSDnumberoptionnel

Loyer mensuel attendu en USD pour une location à long terme(e.g., 2500)

squareFeetnumberoptionnel

Surface en pieds carrés de la propriété(e.g., 1500)

statestringoptionnel

Nom de l'État(e.g., Florida)

citystringoptionnel

Nom de la ville(e.g., St. Petersburg)

countystringoptionnel

Nom du comté(e.g., Pinellas County)

postalCodestringoptionnel

Code postal(e.g., 33703)

countrystringoptionnel

Nom du pays(e.g., United States)

streetstringoptionnel

Nom de la rue(e.g., 2nd Avenue North)

streetNumberstringoptionnel

Numéro de rue(e.g., 4935)

unitstringoptionnel

Numéro d'unité/appartement, le cas échéant

Demande d'exemple

curl -X POST \
  https://atlas.bnbcalc.com/v1/external/analysis/create/owned \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 350000,
  "downPaymentPercentage": 20,
  "interestRatePercentage": 5.1,
  "mortgageLength": 30,
  "yearsRemainingOnMortgage": 30
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/owned',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 350000,
  "downPaymentPercentage": 20,
  "interestRatePercentage": 5.1,
  "mortgageLength": 30,
  "yearsRemainingOnMortgage": 30
})
  }
);
const data = await response.json();

import requests

data = {
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6,
  "purchasePriceUSD": 350000,
  "downPaymentPercentage": 20,
  "interestRatePercentage": 5.1,
  "mortgageLength": 30,
  "yearsRemainingOnMortgage": 30
}

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/analysis/create/owned',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

Réponse d'exemple

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
    "type": "Point",
    "coordinates": [-82.6403, 27.7676],
    "comparables": ["..."],
    "downPaymentPercentage": 20,
    "mortgageLength": 30,
    "yearsRemainingOnMortgage": 30,
    "interestRatePercentage": 5.1,
    "propertyTaxPercentage": 0.75,
    "monthlyRevenueUSD": 5328.730331803278,
    "monthlyExpensesUSD": 1474.1603364983607,
    "monthlyTaxesUSD": 250,
    "yearOneRevenueUSD": 63944.76398163934,
    "yearOneOperatingIncomeUSD": 46254.83994365901,
    "yearOneMorgageAndTaxesUSD": 21324,
    "yearOneCashFlowUSD": 24930.83994365901,
    "yearOneCashOnCashPercentage": 24.86817214984141,
    "yearOneCapRatePercentage": 11.563709985914752,
    "yearOneReturnOnInvestmentPercentage": 63.78402823049849,
    "yearOnePrincipalPaydownUSD": 85635.31658640636,
    "yearOneAppreciationUSD": 12000,
    "totalCashInvestment": 100252,
    "ltrPerMonthUSD": 1500,
    "ltrMonthlyExpensesPercentage": 10,
  }
}

POST/v1/external/analysis/create/cohost

Créer une analyse Cohost

Créer l'historique des co-hôtes

Paramètres de Localisation (Conditionnel)

⚠️ Fournissez soit lat ET lng, soit fullAddress. Au moins une méthode est requise.

latnumberconditionnel

Coordonnée de latitude (doit être fournie avec lng si fullAddress n'est pas utilisée)(e.g., 27.7676)

lngnumberconditionnel

Coordonnée de longitude (doit être fournie avec lat si fullAddress n'est pas utilisée)(e.g., -82.6403)

fullAddressstringconditionnel

Adresse complète de la propriété (peut être utilisée à la place des coordonnées lat/lng)(e.g., 4935 2nd Avenue North, St. Petersburg, FL 33703)

Paramètres Requis

bedroomsnumberobligatoire

Nombre de chambres(e.g., 3)

bathroomsnumberobligatoire

Nombre de salles de bains(e.g., 2)

accomodatesnumberobligatoire

Nombre d'invités que la propriété peut accueillir(e.g., 6)

Paramètres Optionnels

cohostCommissionPercentagenumberoptionnel

Pourcentage de commission du co-hôte(e.g., 10)

squareFeetnumberoptionnel

Surface en pieds carrés de la propriété(e.g., 1500)

statestringoptionnel

Nom de l'État(e.g., Florida)

citystringoptionnel

Nom de la ville(e.g., St. Petersburg)

countystringoptionnel

Nom du comté(e.g., Pinellas County)

postalCodestringoptionnel

Code postal(e.g., 33703)

countrystringoptionnel

Nom du pays(e.g., United States)

streetstringoptionnel

Nom de la rue(e.g., 2nd Avenue North)

streetNumberstringoptionnel

Numéro de rue(e.g., 4935)

unitstringoptionnel

Numéro d'unité/appartement, le cas échéant

Demande d'exemple

curl -X POST \
  https://atlas.bnbcalc.com/v1/external/analysis/create/cohost \
  -H "x-bnbcalc-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6
}'

const response = await fetch(
  'https://atlas.bnbcalc.com/v1/external/analysis/create/cohost',
  {
    method: 'POST',
    headers: {
      'x-bnbcalc-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6
})
  }
);
const data = await response.json();

import requests

data = {
  "lat": 27.7676,
  "lng": -82.6403,
  "bedrooms": 3,
  "bathrooms": 2,
  "accomodates": 6
}

response = requests.post(
    'https://atlas.bnbcalc.com/v1/external/analysis/create/cohost',
    headers={
        'x-bnbcalc-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json=data
)
data = response.json()

Réponse d'exemple

{
  "success": true,
  "data": {
    "_id": "691dab391ecf3015bfba0f5f",
    "url": "https://www.bnbcalc.com/analysis/4935-2nd-ave-n/691dab391ecf3015bfba0f5f",
    currency": "USD",
    "ratePerNightUSD": 364.73770491803276,
    "occupancyRatePercentage": 48,
    "bedrooms": 4,
    "bathrooms": 4,
    "commonSpaces": 1,
    "accomodates": 12,
    "fullAddress": "4935 2nd Avenue North, St. Petersburg, FL 33703",
    "location": {
    "type": "Point",
    "coordinates": [-82.6403, 27.7676],
    "comparables": ["..."],,
    "yearOneRevenueUSD": 161193.91172942825,
    "yearOneCohostReturnUSD": 116059.61644518835,
    "yearOneCohostCommissionUSD": 32238.78234588565,
  }
}

Codes d'erreur

L'API BNBCalc utilise des codes de statut HTTP standard pour indiquer le succès ou l'échec des requêtes API. Les requêtes réussies renvoient des codes 2xx, tandis que les erreurs renvoient des codes 4xx ou 5xx avec des informations d'erreur supplémentaires dans le corps de la réponse.

200

Succès

400

Mauvaise demande - Paramètres invalides

401

Non autorisé - Clé API invalide

429

Trop de demandes - Limite de débit dépassée

500

Erreur interne du serveur