La mise en place d'un widget CityScan se fait en trois étapes :
En créant
une évaluation (une adresse, possiblement associée à un bien), vous pouvez ensuite l'afficher
dans un widget tant que cette évaluation reste active et comptabilisée dans votre période
de consommation courante.
Exemple : Une nouvelle annonce est entrée dans votre système. Vous activez ce bien à l'aide de l'API de création d'une évaluation.
Pour ce faire, il est nécessaire de fournir les éléments suivants dans la requête :
apiKey, clé personnelle fournie en début de
contrat. Cette clé vous sera utile non seulement pour l'activation mais aussi pour la
désactivation des évaluations.
extAddressId. 👉 Ce paramètre optionnel est recommandé
pour utiliser votre propre système d'identifiants, ne pas avoir à enregistrer
des identifiants CityScan ET SURTOUT éviter les doublons.
Si votre identifiant est associé à l'évaluation, il sera possible de gérer l'affichage
de l'adresse dans le widget mais également l'ajout d'un bien immobilier,
la modification de l'évaluation et sa désactivation via votre id.
Sinon, l'id CityScan sera utilisé. Voir aussi le scénario 2.
road/postalCode/city)
latitude/longitude)
avec une précision minimum de 4 chiffres après la virgule.
La précision conseillée est de 6 chiffres après la virgule.
parcel) à partir
duquel on géolocalise et dessine la parcelle.
realty contenant tous les
paramètres
décrits dans la documentation.
🌍 Le service CityScan couvre toute la France métropolitaine.
On reconnait facilement qu'une évaluation est créée grâce au status égal à 0 dans la
réponse.
La réponse de l'API contient notamment l'id CityScan (id),
parfois appelé evaluationId, identifiant qui va vous permettre d'afficher
l'évaluation (que vous venez d'activer) dans un widget.
Des exemples d'activation sont disponibles dans la partie
Scénarios.
Nous insistons sur l'importance de garder votre système d'identifiants.
Exemple : Une nouvelle annonce est entrée dans votre système, elle correspond à
l'entrée AB-123456. Vous activez cette adresse à l'aide de l'API de création en
utilisant le paramètre extAdressId égal à AB-123456. Vous pouvez
maintenant utiliser cette évaluation dans le widget CityScan en utilisant
l'identifiant AB-123456.
Pour plus de détails, vous pouvez vous reporter
à la documentation technique
APIs Évaluations.
En particulier si vous avez créé une évaluation et que la localisation n'est pas tout
à fait exacte, il est possible de corriger son emplacement via l'API de correction PUT.
Des APIs existent également pour vous aider àsuivre votre consommation,
voir la documentation
APIs Suivi de la consommation.
À l'issue de cette étape de création, vous avez maintenant un bien actif
prête à être utilisée dans le widget.
Avant de poursuivre, vérifiez que le nom de domaine du site qui va héberger le widget a
été déclaré auprès de CityScan. En effet le widget ne peut être intégré QUE dans
un site enregistré auprès de CityScan. Si vous avez le moindre doute
ou que vous souhaitez enregistrer de nouveaux sites, contactez le service client CityScan.
Exemple : Votre site web www.monsiteweb.fr a été enregistré chez CityScan au moment
de la configuration de votre widget. Vous pouvez intégrer votre widget sur ce site
mais pas sur www.monsite-d-annonce.fr par exemple.
Pour l'intégration du widget, vous aurez besoin :
La clé de configuration vous permet de personnaliser votre widget, par exemple la
couleur du menu ou l'option de téléchargement de rapport. La ou les clé(s) de
configuration vous sont fournie(s) en début de contrat.
Attention, la clé de configuration (clientKey) est différente de la clé API (apiKey)
qui permet l'activation ou la désactivation des adresses.
Notre librairie JavaScript permet de générer automatiquement le code de l'iframe
contenant le widget. Commencez par inclure la librairie sur votre page web :
<script type="text/javascript" src="https://www.cityscan.fr/assets/build/js/lib/cityscan-widget.js"></script>
Ensuite à l'endroit où vous souhaitez que votre widget apparaisse, intégrez par exemple
le code suivant :
<div id="cityscan-widget" data-ext-address-id="MON_ID" data-client-key="VOTRE_CLIENT_KEY"></div>
Il s'agit ici d'un exemple très simple, libre à vous de rajouter des options au widget, par exemple :
data-id
au lieu de data-ext-address-id.
fr-FR) ou anglais (en-US) via le
paramètre data-language.
data-height et
data-width .
Pour plus de détails et d'exemples, vous pouvez vous reporter à la documentation
technique Intégration
d'un widget. En particulier il est possible d'intégrer le widget directement via
iframe.
Si vous essayez d'utiliser l'identifiant d'une évaluation qui n'a pas été activée, le
widget ne pourra pas s'afficher. Idem si vous tentez d'afficher le widget sur un site
dont le nom de domaine n'a pas été déclaré.
L'évaluation continue d'être comptabilisée dans votre pack tant qu'elle n'a pas été
désactivée, qu'elle doit affichée dans le widget ou non.
Lorsque vous souhaitez archiver ou supprimer votre mandat ou annonce, il est important de
penser à désactiver l'évaluation correspondante pour qu'elle ne soit plus prise en compte
dans le décompte de votre pack lors de la prochaine période de facturation.
Cette désactivation passe un appel à l'API de désactivation.
Avant de procéder à cet appel, bien vérifier qu'aucune page contenant le widget ne
reste visible.
Dès lors que l'évaluation est désactivée, il n'est plus possible de l'afficher dans un widget,
un message d'erreur apparaît : "Pour obtenir une évaluation de cet emplacement,
merci de bien vouloir nous contacter".
Pour utiliser cette API il est nécessaire de fournir les éléments suivants :
On reconnait une désactivation réussie grâce au status égal à 0
dans l'objet évaluation retourné.
Pour plus de détails sur l'API de désactivation, vous pouvez vous reporter
à la documentation technique
Désactiver une évaluation. Pour suivre votre consommation en adresses, voir la documentation
APIs de Recherche et Filtrage.
Rien de mieux que quelques scénarios pour bien comprendre le principe.
Un nouveau mandat vient de tomber pour l'adresse du 15 rue du Miel Joli à Avignon.
Vous ajoutez une nouvelle annonce à votre logiciel. A l'enregistrement de cette annonce,
vous lui liez une activation CityScan, grâce à votre clé API CityScan
"VOTRE_API_KEY" :
raw-json - application/json
POST https://www.cityscan.fr/api/evaluations
Content-Type : application/json
ApiKey : VOTRE_API_KEY
{
"route": "15 rue du Miel Joli",
"postalCode": "84140",
"city": "Avignon",
"extAddressId": "studioMielJolie-1435"
}
Status : 200 OK
Content-Type : application/json
{
"status": 0,
"content": {
"evaluation": {
"id": 246874,
"apiKeyId": 146,
"address": {
"id": 69139,
"route": "15 rue du Miel Joli",
"postalCode": "84140",
"city": "Avignon",
"geoloc": {
"id": 64784,
"lat": "43.939772",
"lon": "4.877358",
"source": "IGN"
}
},
"extAddressId": "studioMielJolie-1435",
"status": 1,
"activation": "2020-08-20 15:26:44",
"deactivation": null,
"lastSeen": null,
"metadata": null
}
}
}
L'évaluation est bien enregistrée ("status":0).
Votre compteur inclut une évaluation en plus.
Si dans votre logiciel de gestion, vous ouvrez la fiche de votre bien et modifiez ses coordonnées, il faudrait que le widget bénéficie des mêmes changements. Pour cela vous allez corriger l'évaluation CityScan.
Maintenant il ne reste plus qu'à intégrer le widget "15 rue du Miel Joli à Avignon" dans votre page annonce sur le site grand public, en déclarant la librairie javascript CityScan (voir plus haut) puis en utilisant le code suivant :
<div id="cityscan-widget" data-ext-address-id=studioMielJolie-1435 data-client-key="VOTRE_CLIENT_KEY"></div>
Votre widget est en place, par exemple :
A noter que les options d'affichage de votre widget dépendent de votre clé de configuration (clientKey).
Au bout de deux mois, l'adresse du 15 rue du Miel Joli à Avignon est vendue, l'annonce a été retirée de votre logiciel ou masquée/archivée. Il faut donc désactiver l'évaluation, pour ne plus continuer à la payer.
raw-json - application/json
POST https://www.cityscan.fr/api/evaluations/deactivate/external/studioMielJolie-1435
Content-Type : application/json
ApiKey : VOTRE_API_KEY
Status : 200 OK
Content-Type : application/json
{
"status": 0,
"content": {
"evaluation": {
"id": 246874,
"apiKeyId": 146,
"address": {
"id": 69139,
"route": "15 rue du Miel Joli",
"postalCode": "84140",
"city": "Avignon",
"geoloc": {
"id": 64784,
"lat": "43.939772",
"lon": "4.877358",
"source": "IGN"
}
},
"extAddressId": "studioMielJolie-1435",
"status": 0,
"activation": "2020-08-20 15:26:44",
"deactivation": "2020-09-28 17:02:15",
"lastSeen": "2020-09-28 15:55:10",
"metadata": null
}
}
}
L'adresse du 15 rue du Miel Joli à Avignon a bien été désactivée
("status": 0).
Elle ne sera plus visible via le widget et elle ne sera pas prise en compte
dans votre compteur d'évaluations facturées lors de la prochaine période de facturation.
NB : Si une adresse masquée peut être à nouveau mise en ligne, selon votre applicatif métier,
vous devez alors
réactiver
l'évaluation CityScan pour retrouver un widget opérationnel.
Vous n'avez pas de CRM ou n'avez pas la main sur celui-ci (type Wordpress) et c'est à la
visualisation d'une annonce que vous voulez récupérer les informations CityScan.
👉 Rappel important : les appels APIs de consommation utilisent la clé API
qui est une clé secrète. Ces appels ne peuvent en aucun cas être fait
côté client/navigateur car ils divulgueraient votre clé secrète.
A l'affichage de votre page, votre applicatif backend doit vérifier l'existance d'une
évaluation CityScan active. Pour cela, faites une
récupération via votre identifiant.
Si vous obtenez un objet null, l'évaluation n'est pas
activée.
Sinon, vous pouvez contrôler son paramètre status et
intégrer cette évaluation à votre page si elle est activée.
Sans CRM, la
désactivation
doit se faire manuellement lors du déréférencement de votre page annonce.
Utilisez des outils comme Postman pour exploiter nos APIs lorsqu'elles ne peuvent pas être
intégrées au sein d'un logiciel ou d'un applicatif web.
Il y a plusieurs façons de ne pas divulguer l'adresse et la position exacte d'un bien sur un widget CityScan :
Vous pouvez mixer les options.
Afficher ou non le marqueur d'adresse est une option à choisir lors de la mise
en place de votre widget. Il est également possible de masquer le marqueur adresse "à la volée", via le paramètre URL noLoc (voir aussi la documentation Intégration du widget).
|
Avec marqueur 
|
Sans marqueur 
|
|---|
Dans le cas d'un widget avec marqueur, vous pouvez choisir d'afficher l'adresse
au survol du marqueur ou non.
Il s'agit d'une option à choisir lors de la mise en place de votre widget. Si vous
souhaitez changer la configuration existante de votre widget, veuillez contacter le
service client CityScan.
Nom de l'adresse au survol (optionnel)
Il est possible de centrer la carte sur un point à proximité de la position exacte de
l'adresse. Le marqueur de l'adresse est toujours placé au centre de la carte, il peut donc
indiquer une position qui n'est pas celle du bien.
Vous avez deux solutions pour décentrer la carte :
Le détail de chacune de ces solutions est détaillé plus bas.
|
Carte centrée sur la position exacte du bien 
|
Carte décentrée(*) 
|
|---|
Le décentrage automatique est une option à choisir lors de la mise en place de votre widget. Elle permet de centrer automatiquement la carte sur un point à une certaine distance de l'adresse. Il n'y a plus qu'à choisir votre niveau de décentrage parmi les trois possibles :
|
Petit décentrage(*) (à environ 100-200 m) 
|
Décentrage moyen(*) (à environ 200-300 m) 
|
Décentrage important(*) (à environ 600-800 m) 
|
|---|
Pour chaque adresse, vous pouvez centrer la carte du widget sur une position de votre
choix, définie par ses coordonnées géographiques. Il s'agit d'un paramètrage à faire
lors de l'intégration du widget. La recommendation est d'utiliser des
latitudes et des longitudes avec au minimum 4 décimales pour une bonne précision. Pour
plus de détails, consulter la documentation Intégration
du widget.
Exemple : Vous voulez recentrer la carte sur le point suivant : latitude=43.231456 /
longitude=-2.123456.
Si vous avez choisi une intégration avec la librairie js, les
paramètres à utiliser sont data-lat et
data-lon :
<div id="cityscan-widget" data-ext-address-id="VOTRE_IDENTIFIANT_ADRESSE" data-client-key="VOTRE_CLIENT_KEY" data-lat="43.231456" data-lon="-2.123456"></div>
Si vous avez choisi une intégration iframe pour le widget, les
paramètres à utiliser sont lat et
lon :
<iframe src="https://www.cityscan.fr/widget?clientKey=VOTRE_CLIENT_KEY&extAddressId=VOTRE_IDENTIFIANT_ADRESSE&lat=43.231456&lon=-2.123456"></iframe>
Cette solution vous offre une flexibilité totale sur la vue que vous renvoyez à votre utilisateur. Elle peut de plus être combinée à un ajustement des niveaux de zoom(**) par adresse.
Pour chaque adresse, vous pouvez choisir d'afficher un disque sur le widget. Ce disque permet de visualiser les emplacements possibles du bien. Il s'agit d'un paramètrage à faire lors de l'intégration du widget. Le rayon du disque (en m) est donné en paramètre lors de l'appel au widget. Pour plus de détails, consulter la documentation Intégration du widget.
|
Ex : Disque de 150 m de rayon 
|
Label au survol du disque (optionnel) 
|
|---|
Vous pouvez choisir le rayon que vous voulez, il n'y a pas de limite sur le rayon
maximum.
Si vous avez choisi une intégration avec la librairie js, le paramètre
à
utiliser est data-radius :
<div id="cityscan-widget" data-ext-address-id="VOTRE_IDENTIFIANT_ADRESSE" data-client-key="VOTRE_CLIENT_KEY" data-radius="150"></div>
Si vous avez choisi une intégration iframe pour le widget, le paramètre
à
utiliser est radius :
<iframe src="https://www.cityscan.fr/widget?clientKey=VOTRE_CLIENT_KEY&extAddressId=VOTRE_IDENTIFIANT_ADRESSE&radius=150"></iframe>
Vous pouvez bien sûr combiner ces différentes options. Voici un exemple d'implémentation pour aider l'utilisateur à se situer sans divulguer la position exacte du bien :
|
Avec décentrage + disque(*) 
|
|---|
La position exacte du bien est masquée. La carte est décentrée sur la position de votre
choix (latitude/longitude à fournir) et un disque de rayon de 150 mètres est tracé pour
aider l'utilisateur à se situer.
Un décentrage automatique est appliqué en cas de tentative de fraude, c'est à dire que
si un
utilisateur arrive à se procurer l'URL du widget il ne pourra pas retrouver la position
exacte du bien même en supprimant de l'URL les paramètres optionnels lat et
lon.
Intégration via la librairie js :
<div id="cityscan-widget" data-ext-address-id="VOTRE_IDENTIFIANT_ADRESSE" data-client-key="VOTRE_CLIENT_KEY" data-lat="47.22415" data-lon="-1.555952" data-radius="150"></div>
Intégration iframe :
<iframe src="https://www.cityscan.fr/widget?clientKey=VOTRE_CLIENT_KEY&extAddressId=VOTRE_IDENTIFIANT_ADRESSE&lat=47.22415&lon=-1.555952&radius=150"></iframe>