Pornire rapidă

Pornește cu API Qarta în 5 minute.

Condiții prealabile

• Cheie API din contul Qarta
• Client HTTP (cURL, Postman sau bibliotecă)
• Familiaritate de bază cu API-urile REST și JSON

Pasul 1: Obțineți cheia API

Contactează managerul de cont Quarticle sau vizitează panoul de control pentru a obține o cheie API.

Pasul 2: Configurare autentificare

Toate cererile la Qarta necesită un antet Authorization cu cheia API:

cURL

curl -X GET "https://graph.quarticle.ro/graph/api/v1/places/geocode?q=New%20York" \
  -H "Authorization: YOUR_API_KEY"

JavaScript

const apiKey = 'YOUR_API_KEY';
const address = 'New York';

const response = await fetch(
  `https://graph.quarticle.ro/graph/api/v1/places/geocode?q=${encodeURIComponent(address)}`,
  {
    headers: {
      'Authorization': `${apiKey}`
    }
  }
);

const data = await response.json();
console.log(data);

Python

import requests

api_key = 'YOUR_API_KEY'
address = 'New York'

response = requests.get(
    'https://graph.quarticle.ro/graph/api/v1/places/geocode',
    params={'q': address},
    headers={'Authorization': api_key}
)

data = response.json()
print(data)

Pasul 3: Faceți prima cerere

Să geocodificăm o adresă pentru a obține coordonatele:

cURL

curl -X GET "https://graph.quarticle.ro/graph/api/v1/places/geocode?q=1600%20Pennsylvania%20Avenue%20Washington%20DC" \
  -H "Authorization: YOUR_API_KEY"

Răspuns:

{
  "result": {
    "lat": 38.8951,
    "lon": -77.0369,
    "label": "1600 Pennsylvania Avenue, Washington, DC",
    "placeId": "abc123",
    "geocodingQuality": "rooftop"
  }
}

JavaScript

const apiKey = 'YOUR_API_KEY';

async function geocodeAddress() {
  const response = await fetch(
    'https://graph.quarticle.ro/graph/api/v1/places/geocode?q=1600%20Pennsylvania%20Avenue%20Washington%20DC',
    {
      headers: {
        'Authorization': `${apiKey}`
      }
    }
  );

  const { result } = await response.json();
  console.log(`Latitude: ${result.lat}, Longitude: ${result.lon}`);
  return result;
}

geocodeAddress();

Python

import requests

api_key = 'YOUR_API_KEY'

headers = {'Authorization': f'{api_key}'}
response = requests.get(
    'https://graph.quarticle.ro/graph/api/v1/places/geocode',
    params={'q': '1600 Pennsylvania Avenue Washington DC'},
    headers=headers
)

result = response.json()['result']
print(f"Latitude: {result['lat']}, Longitude: {result['lon']}")

Pasul 4: Încercați un alt endpoint

Acum încercăm geocodificare inversă (coordonate la adresă):

cURL

curl -X GET "https://graph.quarticle.ro/graph/api/v1/places/geocode/reverse?lat=40.7128&lon=-74.0060" \
  -H "Authorization: YOUR_API_KEY"

JavaScript

const response = await fetch(
  'https://graph.quarticle.ro/graph/api/v1/places/geocode/reverse?lat=40.7128&lon=-74.0060',
  { headers: { 'Authorization': `${apiKey}` } }
);
const { result: address } = await response.json();
console.log(address.label);

Python

response = requests.get(
    'https://graph.quarticle.ro/graph/api/v1/places/geocode/reverse',
    params={'lat': 40.7128, 'lon': -74.0060},
    headers=headers
)
address = response.json()['result']
print(address['label'])

Pasul 5: Variabile de mediu

Nu hardcodifica niciodată cheile API. Utilizează variabile de mediu:

Bash

# Setează variabilă de mediu
export QARTA_API_KEY="YOUR_API_KEY"

# Utilizează în curl
curl -X GET "https://graph.quarticle.ro/graph/api/v1/places/geocode?q=NewYork" \
  -H "Authorization: $QARTA_API_KEY"

JavaScript

// .env file (nu comite niciodată!)
REACT_APP_QARTA_API_KEY=YOUR_API_KEY

// Încarcă în cod
const apiKey = process.env.REACT_APP_QARTA_API_KEY;

Python

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('QARTA_API_KEY')

Erori comune

401 Unauthorized

Cauză: Cheie API nevalidă sau lipsă

Soluție:

• Verifică că cheia API este corectă
• Verifică că nu a expirat
• Asigură-te că cheia API este inclusă în antetul Authorization

400 Bad Request

Cauză: Parametri de cerere nevalidați

Soluție:

• Verifică că parametrii de interogare sunt codificați corespunzător
• Verifică că sunt inclusi parametrii obligatori
• Vezi documentația endpoint pentru valori valide

403 Forbidden

Cauză: Validarea formei geografice a eșuat

Soluție:

• Asigură-te că GeoJSON este valid
• Verifică că coordonatele sunt în ordine [longitudine, latitudine]
• Verifică că coordonatele sunt în WGS84 (EPSG:4326)

Folosești Python?

SDK-ul Python avvolge fiecare endpoint într-un client tipizat cu modele Pydantic, deci poți sări peste apelurile HTTP brute:

from layers_sdk import LayersClient
client = LayersClient(base_url="https://graph.quarticle.ro", api_key="YOUR_API_KEY")
result = client.location.geocode(q="1600 Pennsylvania Avenue Washington DC")
print(result.lat, result.lon)

Descarcă SDK-ul pentru a porni.

Pași următori

• SDK Python - Client Python tipizat pentru toate 36 punctele finale
• Ghid V1 vs V2 - Află despre versiunile API
• Cazuri de utilizare - Vezi exemple practice
• Descarcă colecția Postman - Testează în Postman