Sări la conținutul principal

Export CSV

Qarta suportă exportarea rezultatelor ca fișiere CSV din mai multe puncte finale. Acest ghid arată cum să ceri și să lucrezi cu date CSV.

Puncte finale suportate​

Următoarele puncte finale pot returna format CSV:

EndpointMetodaCale
Căutare intrări (V1)GET/graph/api/v1/reports/portfolio/entries/selection/search
Selecție intrări (V1)POST/graph/api/v1/reports/portfolio/entries/selection
Buffer intrări (V1)POST/graph/api/v1/reports/portfolio/entries/buffer-selection
Căutare intrări (V2)POST/graph/api/v2/reports/portfolio/entries/selection/search
Selecție intrări (V2)POST/graph/api/v2/reports/portfolio/entries/selection
Buffer intrări (V2)POST/graph/api/v2/reports/portfolio/entries/buffer-selection

Notă: Puncte finale și alte tipuri de puncte finale returnează doar JSON.

Cum să ceri CSV​

Formatul CSV este cerut folosind antetul HTTP Accept. Setează-l la text/csv:

Negociere conținut​

Accept: text/csv

Când setezi acest antet, API va răspunde cu date CSV în loc de JSON (dacă punctul final o suportă).

Exemple​

curl -X GET "https://graph.quarticle.ro/graph/api/v1/reports/portfolio/entries/selection/search" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Accept: text/csv" \
  -d "filters={\"field\":\"oe_id\",\"value\":\"portfolio_01\"}&source=portfolio_01&columns=name,value,price"

Sau pentru a salva într-un fișier:

curl -X GET "https://graph.quarticle.ro/graph/api/v1/reports/portfolio/entries/selection/search" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Accept: text/csv" \
  -o "results.csv" \
  -d "filters={\"field\":\"oe_id\",\"value\":\"portfolio_01\"}&source=portfolio_01"

Format CSV​

Răspunsul CSV include:

  • Rând antet - Nume coloane specificate în parametrul columns
  • Rânduri date - Câte unu pe intrare/punct
  • Codificare - UTF-8
  • Delimitator - Virgulă (,)
  • Citare - Câmpurile care conțin virgule sau nueva linie sunt citate

Exemplu ieșire CSV:

name,value,property_type,address
Property A,450000,residential,"123 Main St, Springfield, IL"
Property B,650000,commercial,"456 Oak Ave, Springfield, IL"
Property C,350000,residential,"789 Pine Rd, Springfield, IL"

Selecție coloană​

Controlează care coloane apar în CSV utilizând parametrul columns:

# Include coloane specifice
curl -X GET "https://graph.quarticle.ro/graph/api/v1/reports/portfolio/entries/selection/search" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Accept: text/csv" \
  -d "source=portfolio_01&columns=name,value,address,property_type"

Paginare cu CSV​

Când recuperezi seturi mari de date, utilizează paginare:

import csv
import io

def get_all_entries_csv():
    all_data = []
    page = 0
    page_size = 100

    while True:
        response = requests.get(
            'https://graph.quarticle.ro/graph/api/v1/reports/portfolio/entries/selection/search',
            params={
                'source': 'portfolio_01',
                'limit': page_size,
                'page': page
            },
            headers=headers
        )

        csv_reader = csv.reader(io.StringIO(response.text))
        rows = list(csv_reader)

        if page == 0:
            all_data.extend(rows)
        else:
            all_data.extend(rows[1:])  # Trece peste antet

        if len(rows) <= page_size:
            break
        page += 1

    return all_data

Lucru cu date CSV​

Parsare în Python​

import pandas as pd

# Utilizând pandas (necesită: pip install pandas)
df = pd.read_csv('results.csv')
print(df.head())
print(df.describe())

# Sau utilizând modulul csv
import csv
with open('results.csv', 'r') as f:
    reader = csv.DictReader(f)
    for row in reader:
        print(row)

Răspunsuri eroare​

Chiar și la cerere format CSV, erorile returnează JSON:

{
  "errorMessage": {
    "message": "Invalid source parameter"
  }
}

Verifică codul de stare HTTP pentru a determina dacă cererea a reușit:

  • 200 - Succes (date CSV)
  • 400 - Cerere greșită (eroare JSON)
  • 401 - Neautorizat (eroare JSON)
  • 500 - Eroare server (eroare JSON)

Limitări​

  • CSV este disponibil doar pentru căutare și selecție de intrări/puncte
  • Punctele finale raportare riscuri returnează întotdeauna PDF/HTML
  • Selecția coloane trebuie să specifice nume câmp valide
  • Seturi de date foarte mari pot expira — utilizează paginare

Sfaturi și trucuri​

  1. Gestionare citate - Câmpurile cu virgule, citate sau nueva linie sunt automat citate
  2. Compatibilitate Excel - Fișierele CSV se deschid direct în Excel, Google Sheets, etc.
  3. Exporturi mari - Paginează prin rezultate și concatenează CSV-urile
  4. Codificare - Întotdeauna UTF-8; asigură-te că instrumentele tale gestionează aceasta
  5. Rezultate goale - Returnează doar rând antet dacă nu se potrivesc rezultate

Pași următori​