Skip to main content

IO Reports API

BetaOnly available in EnglishUS 🇺🇸 and Canada 🇨🇦

Description​

IO Reports API is an IO Reports product feature that provides customers with the ability to generate NeighborhoodIntel reports or Neighborhood Market Reports via an API call. With this feature, customers do not need an SSO integration and can generate reports without manual use of the IO Reports dashboard. It can be used to power calls to action, CRM campaigns for leads, and to automatically provide agents and homeseekers with in-depth neighborhood reports at scale.

IO Reports Data Subject to Change

As with reports manually generated and shared, the reports are always loaded with the latest neighborhood data and agent personalization. As new points of interest are added, or scores are recomputed, or neighborhood boundaries change, the contents of IO Reports will change. And as agents update contact information or new profile photos for the reports, past reports are also updated.

Authentication Options​

IO Reports API offers two mechanisms for authentication, outlined below. For any clients wishing to include agent information and personalize the report, the authentication tokens provided below are per-agent.

Local Logic Client ID + Secret​

Once granted access for IO Reports, you can leverage your Local Logic client ID and client secret through a call to get a Local Logic bearer token.

warning

You should never store your Local Logic client ID and client secret on a website, as unauthorized users will be able to access it and generate reports. They could even update reports you've already sent to clients to add filters and remove sections!

You should also never store the returned bearer token on a public website, but it is safe to store these tokens on internal pages.

To retrieve the access_token which can be used for all IO Reports API calls:

# Generic token - no agent personalization or only a single, default agent
https://api.locallogic.co/oauth/token?client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&audience=reports-api

# Personalized token for a specific agent
https://api.locallogic.co/oauth/token?client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&audience=reports-api&agent_id={AGENT_ID}

Custom JWT Flow​

Alternatively, Local Logic can support custom JWT authentication via a "soft" integration to better support front-end generation of reports within a web view (such as tied to buttons or forms on a listing page).

This flow has the following requirements:

  • Local Logic requires a copy of a JWKS (JSON Web Key Set) with public keys to verify JWTs
  • The supplied JWTs are valid for a maximum of 24 hours (after which they will be refused)
  • Local Logic requires a JWT with the following format be passed to 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​

This endpoint is used to generate a report once a valid reports-api bearer token has been retrieved as explained in the above section. It returns both a report ID, and a report URL that can be used as a permalink to load the latest location data for the report location over time.

tip

We recommend using this endpoint to generate always-up-to-date report links for all locations and agents who will use IO Reports. For example, this endpoint can be called each time a new listing is added. Per location, the single returned URL can be saved and shared to multiple users, rather than generating a unique report URL for each individual report that you want to share.

POST v1/reports

This API uses JWT token based authentication. This JWT Bearer token is what is used to populate the Authorization header below.

Instructions on how to retrieve this token can be found in the proceeding sections of this document.

HeaderStatusDescription
AuthorizationrequiredYour bearer token retrieved from our authorization API, ex. Bearer eyJhbGci...
AcceptrequiredThe datatype to request, this API will return application/json.

QueryString​

ParameterStatusDescription
latrequiredA decimal number between -90 and 90, representing the latitude.
lngrequiredA decimal number between -180 and 180, representing the longitude.
address_labelrequiredAn address label to displayed on the front page of the report. It can be the name of a neighborhood, but it generally represents the street address, followed by the city name.
languagerequiredThe language for the report. Currently this is required, but en (English) is the only valid option.
typerequiredThe report type to be generated, either NeighborhoodIntel (for Canada or the US) or Neighborhood Market Report (US-only).
Available: ni and nmr
disabled_pagesoptionalUsed to hide certain sections of the IO Reports upon generation. This is an optional array.
Available (ni): amenities, character, climate, community_portrait, education, highlights, nature, profiles, transportation, trends.
Available (nmr): selling_speed, home_cost, time_to_buy, market_timeframe, market_snapshot, value_drivers.
filtersoptionalOnly valid for Neighborhood Market Reports. Used to specify report filters for the neighborhood, property type, and time frame.
area: An array of valid geog_ids.
property_type: A valid property_type as explained in the market stats API documentation.
time_frame: One of 1y, 3y, or 5y.
Ex: {"area":["g20_dr4e16mj"],"property_type":"condo_townhome","time_frame":"1y"}

Usage examples​

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',
    locale: 'en',
    type: 'nmr'
  })
})
.then(response => response.json())
.then(body => {
  console.log(body)
})
.catch(error => {
  console.log(error)
})

Response example​

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

Additional Report API Endpoints​

This page highlights both the authentication flow for IO Reports API, as well as the options available when generating a report. However, a number of further IO Reports API endpoints are available to support other features and remain available on our auto-generated technical documentation site, including: