Évaluation

Quatre outils d'évaluation. Les appartements, maisons et terrains sont pris en charge ; l'estimation express et le rapport refusent l'immobilier commercial et les ensembles résidentiels avec 422 business_rule ; l'estimation du loyer fonctionne aussi pour l'immobilier commercial.

Estimation express

POST /valuation/express - scope tools:valuation, immédiat. Un appel API plus le prix de l'estimation express.

curl -X POST https://developers.grem.capital/api/v1/valuation/express \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b8c3f7e-2a71-4c55-8d0e-9f1a6b2c4d10" \
  -d '{"propertyCategory":"apartment","addressText":"Torstraße 12, Berlin","totalArea":64,"rooms":2,"currency":"EUR"}'

Réponse :

Pas de surface ou un propertyCategory inconnu - 400 validation ; immobilier commercial - 422 business_rule avec code: commercial_unsupported.

Une évaluation prend 30 à 150 secondes, et le réseau en amont de l'API coupe une réponse non commencée dans les ~100 secondes avec 524. Envoyez donc une Idempotency-Key et l'en-tête Prefer: respond-async : 202 arrive immédiatement avec { "jobId", "status", "state", "links": { "self" } } et les en-têtes Location et Retry-After. Interrogez GET /valuation/express/jobs/{id} (gratuit) jusqu'à ce que state vaille completed (result contient le même corps que le 200 synchrone) ou failed (error contient le même problème). Au lieu d'interroger, vous pouvez vous abonner à express.completed / express.failed (Webhooks). La facturation a lieu une seule fois, comme pour l'appel synchrone ; la tâche est conservée 7 jours. Sans l'en-tête, la réponse reste synchrone.

Rapport d'évaluation complet

POST /valuation/report - scope tools:valuation, tâche. Un rapport avec analyse de marché et un PDF. Les champs obligatoires dépendent de propertyCategory. N'envoyez que les champs de votre catégorie : un champ d'une autre catégorie (par exemple houseLevels pour un appartement, parking pour une maison) est refusé avec 400. Appartement uniquement : livingArea, kitchenArea, bathrooms, ceilingHeight, floor, storeys, balcony, elevator, parking, houseType, apartmentType. Maison uniquement : houseLevels. Terrain uniquement : zoning. Maison et terrain : utilities.

curl -X POST https://developers.grem.capital/api/v1/valuation/report \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyCategory": "apartment",
    "address": { "country": "Germany", "city": "Berlin", "street": "Torstraße", "streetNumber": "12" },
    "currency": "EUR", "language": "eng",
    "apartmentType": "Residential", "houseType": "panel",
    "totalArea": 64, "rooms": 2, "floor": 3, "storeys": 5,
    "balcony": true, "elevator": false, "condition": "good"
  }'

Réponse 202 : { "jobId": "...", "status": "processing", "state": "running" }. La tâche terminée (GET /valuation/report/jobs/{id}) contient :

L'immobilier commercial (y compris apartmentType Commercial ou Industrial) est refusé avec 422 business_rule et code: commercial_unsupported - estimez plutôt son loyer avec POST /valuation/rent. Un ensemble résidentiel (apartmentType: Complex) - 422 avec code: complex_unsupported : évaluez un appartement ou une maison de cet ensemble.

PDF : GET /artifacts/v1/ai/appraisal/reports/{id}/pdf. Événements - valuation.completed / valuation.failed.

Estimation du loyer

POST /valuation/rent - scope tools:rent, immédiat. Décrivez le bien avec des champs ou passez l'objectId de votre annonce ou d'une annonce publique.

curl -X POST https://developers.grem.capital/api/v1/valuation/rent \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"propertyCategory":"apartment","country":"Germany","city":"Berlin","totalArea":50,"rooms":2,"currency":"EUR"}'

Réponse :

Sans surface ou sans ville - 400 avec un detail du type "Missing or invalid: totalArea".

Une estimation du loyer peut aussi prendre plus d'une minute. Avec Prefer: respond-async, elle répond immédiatement 202 avec une tâche ; statut : GET /valuation/rent/jobs/{id} (gratuit), événements : rent.completed / rent.failed. Tout le reste fonctionne comme pour l'estimation express ci-dessus.

Vérification de rapport

POST /valuation/review - scope tools:review. Téléversez un rapport d'évaluation (PDF, DOCX, DOC, RTF ; jusqu'à 40 MB) - GREM le lit et vérifie la valeur au regard des données du marché.

Corps - multipart/form-data :

curl -X POST https://developers.grem.capital/api/v1/valuation/review \
  -H "Authorization: Bearer gsk_live_xxx" \
  -F "file=@report.pdf" \
  -F "language=eng" -F "currency=EUR"

Le document est lu immédiatement. La réponse 202 contient jobId, status et state :

• action_required (status: need_confirm) - extracted contient les données lues dans le document. Vérifiez-les et confirmez : POST /valuation/review/jobs/{id}/confirm (Tâches et résultats). Après confirmation, la tâche passe à running.
• failed (status: rejected) - le document n'est pas un rapport d'évaluation immobilière.

Le résultat final - GET /valuation/review/jobs/{id} ; le rapport de vérification - GET /artifacts/v1/ai/appraisal/reviews/{id}/report.pdf ou report.docx. Événements - review.completed / review.failed ; le suivi par webhook commence après la confirmation. Quand le document est lu et doit être confirmé, l’événement review.action_required arrive avec l’id de la vérification.

La lecture d'un gros document peut prendre plusieurs minutes, et une réponse non commencée dans les ~100 secondes est coupée avec 524. Avec une Idempotency-Key et l'en-tête Prefer: respond-async, le 202 arrive dès que le fichier est téléversé, avec une tâche de requête (jobId du type areq_…, Preference-Applied: respond-async, Location, Retry-After). Interrogez GET /valuation/review/jobs/{id} avec cet identifiant (gratuit) jusqu'à ce que state vaille completed : result contient exactement le 202 décrit ci-dessus - utilisez son result.jobId pour récupérer la vérification et la confirmer (POST /valuation/review/jobs/{id}/confirm). Pour une tâche de requête, review.completed signifie que le document est lu et attend une confirmation. Une tâche échouée avec code: interrupted n'est pas facturée et libère la clé : renvoyez la même requête avec la même clé. Sans l'en-tête, la réponse reste la même qu'avant.

Voir aussi

• Tâches et résultats
• Erreurs
• Limites et facturation