Quickstart

Get started with Qarta API in 5 minutes.

Prerequisites

• API key from your Qarta account
• HTTP client (cURL, Postman, or library)
• Basic familiarity with REST APIs and JSON

Step 1: Get Your API Key

Contact your Quarticle account manager or visit your dashboard to obtain an API key.

Step 2: Set Up Authentication

All requests to Qarta require an Authorization header with your API key:

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)

Step 3: Make Your First Request

Let's geocode an address to get its coordinates:

cURL

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

Response:

{
  "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']}")

Step 4: Try Another Endpoint

Now let's try reverse geocoding (coordinates to address):

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'])

Step 5: Environment Variables

Never hardcode API keys. Use environment variables:

Bash

# Set environment variable
export QARTA_API_KEY="YOUR_API_KEY"

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

JavaScript

// .env file (never commit!)
REACT_APP_QARTA_API_KEY=YOUR_API_KEY

// Load in code
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')

Common Errors

401 Unauthorized

Cause: Invalid or missing API key

Solution:

• Verify your API key is correct
• Check that it hasn't expired
• Ensure your API key is included in the Authorization header

400 Bad Request

Cause: Invalid request parameters

Solution:

• Check query parameters are properly encoded
• Verify required parameters are included
• See endpoint documentation for valid values

403 Forbidden

Cause: Geographic shape validation failed

Solution:

• Ensure GeoJSON is valid
• Verify coordinates are in [longitude, latitude] order
• Check coordinates are in WGS84 (EPSG:4326)

Using Python?

The Python SDK wraps every endpoint in a typed client with Pydantic models, so you can skip the raw HTTP calls entirely:

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)

Download the SDK to get started.

Next Steps

• Python SDK - Typed Python client for all 36 endpoints
• V1 vs V2 Guide - Learn about API versions
• Use Cases - See practical examples
• Download Postman Collection - Test in Postman