Synkroniser data

Denne veiledningen viser hvordan du holder en kopi av eiendommene dine fra Telescope i ditt eget system, for eksempel et datavarehus, en database eller en intern app. For Power BI følger du heller Power BI-veiledningen.

Paginering

Listeendepunktene returnerer opptil 100 elementer per side, med de sist opprettede først:

{
  "next": "https://api.telescope.eco/external/properties/?cursor=cD0yMDI2...",
  "previous": null,
  "results": [{ "id": "...", "name": "...", "updated_at": "..." }]
}

Fortsett å hente next til den er null. Sidestørrelsen er fast.

• Behandle pekeren (cursor) som ugjennomsiktig. Ikke bygg eller endre den selv.
• Følg bare next til Telescope. Den tryggeste måten er å lese spørreparameteren cursor fra next og sende den til base-URL-en du har satt opp, sammen med de andre spørreparameterne dine. Da kan API-nøkkelen din aldri bli sendt til en annen vert.

En pålitelig synkronisering

Hver kjøring henter hele listen og erstatter kopien din:

1. Hent alle sidene av /external/properties/.
2. Oppdater eller opprett (upsert) hver eiendom etter id i kopien din.
3. Fjern resten. API-et rapporterer ikke slettinger, så slett eiendommene i kopien din som denne kjøringen ikke returnerte.

Dette er verdt å få riktig:

• Fjern først etter siste side. Hvis en kjøring feiler halvveis, kan en eiendom du ikke fikk, ligge på en side du aldri hentet.
• Endringer underveis er trygge. Sidene er sortert etter når eiendommen ble opprettet, så en eiendom som endres, flyttes ikke til en annen side. En eiendom som opprettes under en kjøring, kommer med i neste.
• Kjør den etter en tidsplan, for eksempel hver natt. Hver kjøring henter også de nyeste klimafare- og naturmangfoldresultatene, bygningene og energiattestene.

Nøstede resultater

En eiendoms updated_at endres bare når selve eiendommen endres. Nye eller endrede klimafareresultater, naturmangfoldresultater, bygninger og energiattester endrer den ikke. Hvert klimafare- og naturmangfoldresultat har sin egen updated_at, så du kan se hvilke resultater som er endret siden forrige kjøring.

For å hente de oppdaterte resultatene til én eiendom mellom kjøringene, bruker du GET /external/properties/{id}/.

Eksempel i Python

from urllib.parse import parse_qs, urlparse

import requests

BASE_URL = "https://api.telescope.eco"
session = requests.Session()
session.headers["X-API-Key"] = "your-secret"


def list_all(path: str, **params) -> list[dict]:
    results = []
    while True:
        response = session.get(f"{BASE_URL}{path}", params=params, timeout=60)
        response.raise_for_status()
        page = response.json()
        results.extend(page["results"])
        if not page["next"]:
            return results
        # Only the cursor is taken from `next`, so the key never leaves BASE_URL
        params["cursor"] = parse_qs(urlparse(page["next"]).query)["cursor"][0]


def sync(ids_in_your_copy: set[str]) -> None:
    properties = list_all("/external/properties/")
    for prop in properties:
        upsert_property(prop)  # your storage, keyed by prop["id"]
    # Reached only after the last page, so a failed run removes nothing
    for property_id in ids_in_your_copy - {prop["id"] for prop in properties}:
        delete_property(property_id)

Mapper

GET /external/portfolios/ lister bare rotmapper. For å få hele treet henter du detaljene for hver mappe, som inkluderer undermappene som ligger rett under den, og gjentar for hver undermappe:

GET /external/portfolios/                 → root portfolios
GET /external/portfolios/{id}/            → that portfolio's child portfolios and properties

Hver eiendom har også sin portfolio_id, så du kan plassere eiendommene i treet uten å gå gjennom mappedetaljene.

Filtrer det du henter

Eiendomslisten tar imot filtre, for eksempel for å hente bare eiendommer med relevant jordskredfare og høy eksponering:

GET /external/properties/?hazard=landslide&exposure=HIGH,VERY_HIGH&hazard_relevant=true

Se filtre for eiendommer for alle filtrene.

Generer en typet klient

OpenAPI-skjemaet fungerer med kodegeneratorer som OpenAPI Generator eller openapi-python-client. Mange generatorer sender Authorization: Bearer som standard. Sett dem opp til å sende nøkkelen i headeren X-API-Key i stedet, uten prefiks.