IO Reports API

StableOffert en anglais seulementÉ.-U. 🇺🇸 et Canada 🇨🇦

Description

IO Reports API est une fonctionnalité du produit IO Reports qui permet aux clients de générer des Neighborhood Lifestyle Report ou des Neighborhood Market Report au moyen d'un appel API. Grâce à cette fonctionnalité, les clients n'ont pas besoin d'une intégration SSO et peuvent générer des rapports sans utiliser manuellement le tableau de bord IO Reports. Elle peut servir à alimenter des appels à l'action, des campagnes CRM destinées aux prospects, et à fournir automatiquement aux agents et aux chercheurs de logement des rapports de quartier approfondis, à grande échelle.

Les données des IO Reports peuvent changer

Comme pour les rapports générés et partagés manuellement, les rapports sont toujours chargés avec les données de quartier les plus récentes et la personnalisation de l'agent. À mesure que de nouveaux points d'intérêt sont ajoutés, que les scores sont recalculés ou que les limites de quartier changent, le contenu des IO Reports change. De même, lorsque les agents mettent à jour leurs coordonnées ou leur photo de profil pour les rapports, les rapports déjà générés sont eux aussi mis à jour.

Options d'authentification

IO Reports API offre deux mécanismes d'authentification, décrits ci-dessous. Pour tout client souhaitant inclure des informations sur l'agent et personnaliser le rapport, les jetons d'authentification fournis ci-dessous sont propres à chaque agent.

ID client et secret Local Logic

Une fois l'accès aux IO Reports accordé, vous pouvez utiliser votre ID client Local Logic et votre secret client au moyen d'un appel permettant d'obtenir un jeton porteur Local Logic.

attention

Vous ne devriez jamais stocker votre ID client Local Logic et votre secret client sur un site Web, car des utilisateurs non autorisés pourraient y accéder et générer des rapports. Ils pourraient même modifier des rapports que vous avez déjà envoyés à des clients pour y ajouter des filtres ou en retirer des sections!

Vous ne devriez jamais non plus stocker le jeton porteur retourné sur un site Web public, mais il est sécuritaire de conserver ces jetons sur des pages internes.

Pour récupérer le access_token pouvant être utilisé pour tous les appels de IO Reports API :

# Jeton générique - aucune personnalisation d'agent ou un seul agent par défaut
POST https://api.locallogic.co/oauth/token
Body:
{  
   "client_id"="{CLIENT_ID}",
   "client_secret"="{CLIENT_SECRET}",
   "audience"="reports-api"
}

# Jeton personnalisé pour un agent en particulier
POST https://api.locallogic.co/oauth/token
Body:
{  
   "client_id"="{CLIENT_ID}",
   "client_secret"="{CLIENT_SECRET}",
   "audience"="reports-api",
   "agent_id"="{AGENT_ID}"
}

Flux JWT personnalisé

Autrement, Local Logic peut prendre en charge une authentification JWT personnalisée au moyen d'une intégration « souple » afin de mieux prendre en charge la génération de rapports côté client à l'intérieur d'une vue Web (par exemple liée à des boutons ou des formulaires sur une page d'inscription).

Ce flux comporte les exigences suivantes :

• Local Logic requiert une copie d'un JWKS (JSON Web Key Set) contenant des clés publiques pour valider les JWT
• Les JWT fournis sont valides pour une durée maximale de 24 heures (après quoi ils seront refusés)
• Local Logic requiert qu'un JWT respectant le format suivant soit transmis à https://api.locallogic.co/oauth/token :

{
  "iss": "{YOUR_API_DOMAIN}",
  "sub": "{AGENT_CLIENT_ID}@clients",
  "aud": "https://reports-api.locallogic.co/",
  "gty": "client_credentials",
  "azp": "{AGENT_CLIENT_ID}",
  "provider": "{PROVIDER_CODE}",
  "iat": {ISSUED_UNIX_TIMESTAMP},
  "exp": {EXPIRY_UNIX_TIMESTAMP}
}

POST /v1/reports

Ce point de terminaison sert à générer un rapport une fois qu'un jeton porteur reports-api valide a été récupéré, comme expliqué à la section précédente. Il retourne à la fois un ID de rapport et une URL de rapport pouvant être utilisée comme lien permanent pour charger les données de localisation les plus récentes pour l'emplacement du rapport, au fil du temps.

astuce

Nous recommandons d'utiliser ce point de terminaison pour générer des liens de rapport toujours à jour pour tous les emplacements et agents qui utiliseront IO Reports. Par exemple, ce point de terminaison peut être appelé chaque fois qu'une nouvelle inscription est ajoutée. Par emplacement, l'unique URL retournée peut être enregistrée et partagée à plusieurs utilisateurs, plutôt que de générer une URL de rapport unique pour chaque rapport individuel que vous souhaitez partager.

POST /v1/reports

En-tête

Cette API utilise une authentification basée sur un jeton JWT. Ce jeton porteur JWT est ce qui sert à remplir l'en-tête Authorization ci-dessous.

Les instructions pour récupérer ce jeton se trouvent dans les sections précédentes de ce document.

Header	Status	Description
Authorization	requis	Votre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci...
Accept	requis	Le type de données à demander; cette API retournera application/json.

Paramètres du corps

Parameter	Status	Description
lat	optionnel*	Un nombre décimal entre -90 et 90, représentant la latitude. * Requis pour les rapports basés sur une adresse, qui sont générés à partir de la latitude et de la longitude.
lng	optionnel*	Un nombre décimal entre -180 et 180, représentant la longitude. * Requis pour les rapports basés sur une adresse, qui sont générés à partir de la latitude et de la longitude.
geog_id	optionnel*	Le geog_id pour les rapports basés sur un quartier. Les géographies valides sont celles sous le niveau 40 : celles commençant par g10_, g20_, g30_, g32_, g35_, g37_ et g38_. * Requis pour les rapports basés sur une géographie, qui concernent un quartier ou une municipalité entière.
address_label	optionnel*	Une étiquette d'adresse à afficher sur la page couverture du rapport. Il peut s'agir du nom d'un quartier, mais elle représente généralement l'adresse municipale, suivie du nom de la ville. * Requis pour les rapports basés sur une adresse, qui sont générés à partir de la latitude et de la longitude. Pour les rapports basés sur une géographie, le nom du quartier ou de la communauté est utilisé par défaut.
language	requis	La langue du rapport. Ce champ est actuellement requis, mais en (anglais) est la seule option valide.
type	requis	Le type de rapport à générer, soit Neighborhood Lifestyle Report (pour le Canada ou les États-Unis; anciennement NeighborhoodIntel) ou Neighborhood Market Report (États-Unis seulement). Valeurs disponibles : ni et nmr
disabled_pages	optionnel	Sert à masquer certaines sections des IO Reports lors de la génération. Il s'agit d'un tableau optionnel. Disponible (ni) : amenities, character, climate, community_portrait, education, highlights, nature, profiles, transportation, trends. Disponible (nmr) : selling_speed, home_cost, time_to_buy, market_timeframe, market_snapshot, value_drivers.
filters	optionnel	Valide uniquement pour les Neighborhood Market Report. Sert à préciser les filtres de rapport pour le quartier, le type de propriété et la période. area : un tableau de geog_id valides.*** property_type : un property_type valide, tel qu'expliqué dans la documentation de l'API Market Stats. time_frame : l'une des valeurs 1y, 3y ou 5y. Ex. : {"area":["g20_dr4e16mj"],"property_type":"condo_townhome","time_frame":"1y"}

Exemples d'utilisation

NodeJS

// Rapport basé sur l'adresse
require('node-fetch')('https://reports-api.locallogic.co/v1/reports', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer eyJhbGciOiJ...'
  },
  body: JSON.stringify({
    lat: 39.92422,
    lng: -75.15548,
    address_label: '500 Dudley St, Philadelphia, PA 19148',
    language: 'en',
    type: 'nmr'
  })
})
.then(response => response.json())
.then(body => {
  console.log(body)
})
.catch(error => {
  console.log(error)
})

// Rapport basé sur la géographie
require('node-fetch')('https://reports-api.locallogic.co/v1/reports', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer eyJhbGciOiJ...'
  },
  body: JSON.stringify({
    geog_id: 'g20_dr4e16mj',
    language: 'en',
    type: 'nmr'
  })
})
.then(response => response.json())
.then(body => {
  console.log(body)
})
.catch(error => {
  console.log(error)
})

Python

import requests

# Rapport basé sur l'adresse
response = requests.post(
  "https://reports-api.locallogic.co/v1/reports",
  headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ..."},
  json={
    "lat": 39.92422,
    "lng": -75.15548,
    "address_label": "500 Dudley St, Philadelphia, PA 19148",
    "language": "en",
    "type": "nmr"
  }
)

print(response.json())

# Rapport basé sur la géographie
response = requests.post(
  "https://reports-api.locallogic.co/v1/reports",
  headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ..."},
  json={
    "geog_id": "g20_dr4e16mj",
    "language": "en",
    "type": "nmr"
  }
)

print(response.json())

Exemple de réponse

{
  "report_id": "75952235-13af-48c1-88af-5715a228844a",
  "report_url": "https://neighborhoodintel.locallogic.co/nmr/75952235-13af-48c1-88af-5715a228844a"
}

PATCH /v1/agents/me

Ce point de terminaison sert à mettre à jour le profil d'un agent afin de permettre la personnalisation d'un rapport. La personnalisation est liée à un jeton porteur précis, selon le agent_id. Pour un exemple plus complet de la façon dont cela peut fonctionner dans un flux d'intégration, veuillez consulter le guide Personnalisation des rapports via l'API.

Bien que cela ne soit pas documenté séparément sur cette page, l'exécution d'un appel à GET https://reports-api.locallogic.co/v1/agents/me retournera les paramètres de profil actuellement actifs associés au jeton porteur donné.

PATCH /v1/agents/me

En-tête

Cette API utilise une authentification basée sur un jeton JWT. Ce jeton porteur JWT est ce qui sert à remplir l'en-tête Authorization ci-dessous.

Les instructions pour récupérer ce jeton se trouvent dans les sections précédentes de ce document.

Header	Status	Description
Authorization	requis	Votre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci...
Accept	requis	Le type de données à demander; cette API retournera application/json.

Paramètres du corps

Parameter	Status	Description
first_name	optionnel	Le prénom de l'utilisateur pour le profil de l'agent. Limite de 20 caractères.
last_name	optionnel	Le nom de famille de l'utilisateur pour le profil de l'agent. Limite de 20 caractères.
company_name	optionnel	Le nom de l'entreprise pour le profil de l'agent. Limite de 50 caractères.
company_website	optionnel	L'URL du site Web de l'entreprise pour le profil de l'agent. Limite de 150 caractères.
description	optionnel	La biographie ou la description de l'utilisateur pour le profil de l'agent. Limite de 300 caractères.
email	optionnel	L'adresse courriel de l'utilisateur pour le profil de l'agent. Limite de 50 caractères.
is_personalization_active	optionnel	Une valeur booléenne TRUE/FALSE indiquant si les rapports de cet utilisateur afficheront son profil d'agent. Cette option peut être activée rétroactivement et touche tous les rapports générés pour un utilisateur donné.
links	optionnel	Un tableau d'un maximum de 3 chaînes de caractères représentant des URL pour des liens sociaux ou d'autres profils en ligne. Chaque chaîne du tableau doit comporter 150 caractères ou moins.
phone	optionnel	Le numéro de téléphone de l'utilisateur pour le profil de l'agent. Limite de 12 caractères. Aucun formatage n'est appliqué à cette valeur dans le rapport lui-même; incluez donc les traits d'union et le formatage nécessaire.

Exemples d'utilisation

NodeJS

// Mettre à jour le profil
require('node-fetch')('https://reports-api.locallogic.co/v1/agents/me', {
  method: 'PATCH',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer eyJhbGciOiJ...'
  },
  body: JSON.stringify({
    first_name: 'John',
    last_name: 'Smith',
    email: 'john.smith@gmail.com',
    phone: '706-999-9999'
  })
})
.then(response => response.json())
.then(body => {
  console.log(body)
})
.catch(error => {
  console.log(error)
})

// Obtenir le profil actuel
require('node-fetch')('https://reports-api.locallogic.co/v1/agents/me', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer eyJhbGciOiJ...'
  }
})
.then(response => response.json())
.then(body => {
  console.log(body)
})
.catch(error => {
  console.log(error)
})

Python

import requests

# Mettre à jour le profil
response = requests.patch(
  "https://reports-api.locallogic.co/v1/agents/me",
  headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ..."},
  json={
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@gmail.com",
    "phone": "706-999-9999"
  }
)

print(response.json())

# Obtenir le profil actuel
response = requests.get(
  "https://reports-api.locallogic.co/v1/agents/me",
  headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ..."}
)

print(response.json())

Exemple de réponse

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@gmail.com",
  "phone": "706-999-9999"
}

PUT /v1/agents/me/logo

Ce point de terminaison sert à téléverser un logo d'agent personnalisé à afficher sur les rapports. La personnalisation (y compris le logo) est liée à un jeton porteur précis, selon le agent_id. La taille maximale du logo est de 10 Mo.

PUT /v1/agents/me/logo

En-tête

Cette API utilise une authentification basée sur un jeton JWT. Ce jeton porteur JWT est ce qui sert à remplir l'en-tête Authorization ci-dessous.

Les instructions pour récupérer ce jeton se trouvent dans les sections précédentes de ce document.

Header	Status	Description
Authorization	requis	Votre jeton porteur récupéré depuis notre API d'autorisation, ex. Bearer eyJhbGci...
Accept	requis	Le type de données à demander; cette API retournera application/json.

Paramètres du corps

Parameter	Status	Description
logo	requis	Le logo de l'utilisateur pour les IO Reports personnalisés. Envoyé sous forme de données binaires, avec un maximum de 10 Mo

Exemples d'utilisation

NodeJS

// Mettre à jour le profil
const fs = require('fs');
const FormData = require('form-data');
const form = new FormData();
form.append('logo', fs.createReadStream('logo.png'));
const imageBuffer = fs.readFileSync('logo.png');
require('node-fetch')('https://reports-api.locallogic.co/v1/agents/me/logo', {
  method: 'PUT',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer eyJhbGciOiJ...',
    form.getHeaders()
  },
  body: form
})
.then(response => response.json())
.then(body => {
  console.log(body)
})
.catch(error => {
  console.log(error)
})

Python

import requests

with open("awesome-logo.png", "rb") as fp:
binary_data = fp.read()

response = requests.put(
  "https://reports-api.locallogic.co/v1/agents/me/logo",
  headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ...",
    "Content-Type": "multipart/form-data"},
  json={
    "logo": binary_data
  }
)

print(response.json())

Points de terminaison supplémentaires de l'API Report

Cette page présente à la fois le flux d'authentification de IO Reports API et les options disponibles lors de la génération d'un rapport. Cependant, un certain nombre d'autres points de terminaison de IO Reports API sont disponibles pour prendre en charge d'autres fonctionnalités et demeurent accessibles sur notre site de documentation technique généré automatiquement, notamment :

• Mise à jour du logo d'un agent qui apparaît sur le rapport
• Récupération d'une liste de rapports générés par un agent
• Mise à jour d'un rapport précis pour modifier des filtres ou ajouter/retirer des sections