Atlas API API Reference

Complete API documentation for geographic data in English and Arabic.

About SolvyAtlas API

SolvyAtlas API provides comprehensive geographic data for countries, governorates, and cities in both English and Arabic. Access structured location data with bilingual support, perfect for building address forms, location pickers, shipping calculators, and regional analytics applications.

📍 Currently Available

🇪🇬 Egypt

🚀 More countries coming soon! Stay tuned for updates.

🎉 Free Access

The SolvyAtlas API is currently completely free to use during our launch period. Get your API credentials and start building today!

ℹ️ Please note: Subscription fees may be introduced in the future. Early adopters will receive special benefits and advance notice of any pricing changes.

API Overview

These endpoints require authentication using both a Public Key and Secret Key. After requesting access, you will receive your API credentials for free.

Base URL

https://atlasapi.solvytix.com

Authentication

Include both keys in your request headers:

X-Public-Key: YOUR_PUBLIC_KEY
X-Secret-Key: YOUR_SECRET_KEY

Important: Keep your Secret Key confidential. Never expose it in client-side code or public repositories.

Language Selection

Specify your preferred language by including the Accept-Language header:

Accept-Language: en    // For English
Accept-Language: ar    // For Arabic

Endpoints without /with-translations return data in the language specified in the header. Endpoints with /with-translations return data in both English and Arabic simultaneously.

All endpoints return application/json.

Country Endpoints

GET /api/Countries
Returns list of countries in the language specified in request headers (English or Arabic).

Response Example:

[
  {
    "id": 1,
    "code": "EG",
    "name": "Egypt"
  }
]
GET /api/Countries/with-translations
Returns countries with English and Arabic names including translation metadata.

Response Example:

[
  {
    "id": 1,
    "code": "EG",
    "translations": [
      {
        "language": "en",
        "name": "Egypt"
      },
      {
        "language": "ar",
        "name": "مصر"
      }
    ]
  }
]
GET /api/Countries/{id}
Returns country details by ID in the language specified in request headers.

Parameters:

id (path) - Country ID (integer)

Response Example:

{
  "id": 1,
  "code": "EG",
  "name": "Egypt"
}

Governorate Endpoints

GET /api/Governrate
Returns list of governorates in the language specified in request headers (English or Arabic).

Response Example:

[
  {
    "id": 1,
    "countryId": 1,
    "name": "Cairo"
  }
]
GET /api/Governrate/with-translations
Returns governorates with English and Arabic names including translation metadata.

Response Example:

[
  {
    "id": 1,
    "countryId": 1,
    "translations": [
      {
        "language": "en",
        "name": "Cairo"
      },
      {
        "language": "ar",
        "name": "القاهرة"
      }
    ]
  }
]
GET /api/Governrate/{id}
Returns governorate by ID in the language specified in request headers.

Parameters:

id (path) - Governorate ID (integer)

Response Example:

{
  "id": 1,
  "countryId": 1,
  "name": "Cairo"
}

City Endpoints

GET /api/Cities
Returns list of cities in the language specified in request headers (English or Arabic).

Response Example:

[
  {
    "id": 1,
    "governorateId": 1,
    "name": "Nasr City"
  }
]
GET /api/Cities/with-translations
Returns cities with English and Arabic names including translation metadata.

Response Example:

[
  {
    "id": 1,
    "governorateId": 1,
    "translations": [
      {
        "language": "en",
        "name": "Nasr City"
      },
      {
        "language": "ar",
        "name": "مدينة نصر"
      }
    ]
  }
]
GET /api/Cities/with-translations/{governrateId}
Returns cities filtered by governorate with English and Arabic names.

Parameters:

governrateId (path) - Governorate ID (integer)

Response Example:

[
  {
    "id": 1,
    "governorateId": 1,
    "translations": [
      {
        "language": "en",
        "name": "Nasr City"
      },
      {
        "language": "ar",
        "name": "مدينة نصر"
      }
    ]
  }
]
GET /api/Cities/governorate/{governorateId}
Returns cities by governorate ID in the language specified in request headers.

Parameters:

governorateId (path) - Governorate ID (integer)

Response Example:

[
  {
    "id": 1,
    "governorateId": 1,
    "name": "Nasr City"
  }
]
GET /api/Cities/{id}
Returns city details by ID in the language specified in request headers.

Parameters:

id (path) - City ID (integer)

Response Example:

{
  "id": 1,
  "governorateId": 1,
  "name": "Nasr City"
}

Usage Examples

async function getCountries(publicKey, secretKey, language = 'en') {
  const res = await fetch('https://atlasapi.solvytix.com/api/Countries', {
    headers: {
      'X-Public-Key': publicKey,
      'X-Secret-Key': secretKey,
      'Accept-Language': language  // 'en' for English, 'ar' for Arabic
    }
  });
  return res.json();
}

// Example usage - Get countries in English
const data = await getCountries('your_public_key', 'your_secret_key', 'en');

// Example usage - Get countries in Arabic
const dataAr = await getCountries('your_public_key', 'your_secret_key', 'ar');
using System;
using System.Net.Http;
using System.Threading.Tasks;

public class AtlasApiClient
{
    private readonly HttpClient _httpClient;
    private readonly string _publicKey;
    private readonly string _secretKey;

    public AtlasApiClient(string publicKey, string secretKey)
    {
        _publicKey = publicKey;
        _secretKey = secretKey;
        _httpClient = new HttpClient();
    }

    public async Task<string> GetCountriesAsync(string language = "en")
    {
        var request = new HttpRequestMessage(HttpMethod.Get, 
            "https://atlasapi.solvytix.com/api/Countries");
        
        request.Headers.Add("X-Public-Key", _publicKey);
        request.Headers.Add("X-Secret-Key", _secretKey);
        request.Headers.Add("Accept-Language", language);  // "en" or "ar"

        var response = await _httpClient.SendAsync(request);
        response.EnsureSuccessStatusCode();
        
        return await response.Content.ReadAsStringAsync();
    }
}

// Example usage
var client = new AtlasApiClient("your_public_key", "your_secret_key");
var countries = await client.GetCountriesAsync("en");  // English
var countriesAr = await client.GetCountriesAsync("ar");  // Arabic
import requests

class AtlasApiClient:
    def __init__(self, public_key, secret_key):
        self.public_key = public_key
        self.secret_key = secret_key
        self.base_url = "https://atlasapi.solvytix.com/api"
    
    def get_countries(self, language='en'):
        """
        Get countries list
        language: 'en' for English, 'ar' for Arabic
        """
        headers = {
            'X-Public-Key': self.public_key,
            'X-Secret-Key': self.secret_key,
            'Accept-Language': language
        }
        
        response = requests.get(
            f'{self.base_url}/Countries',
            headers=headers
        )
        response.raise_for_status()
        return response.json()

# Example usage
client = AtlasApiClient('your_public_key', 'your_secret_key')

# Get countries in English
countries = client.get_countries('en')

# Get countries in Arabic
countries_ar = client.get_countries('ar')
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class AtlasApiClient {
    private final HttpClient httpClient;
    private final String publicKey;
    private final String secretKey;
    private static final String BASE_URL = "https://atlasapi.solvytix.com/api";

    public AtlasApiClient(String publicKey, String secretKey) {
        this.publicKey = publicKey;
        this.secretKey = secretKey;
        this.httpClient = HttpClient.newHttpClient();
    }

    public String getCountries(String language) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/Countries"))
            .header("X-Public-Key", publicKey)
            .header("X-Secret-Key", secretKey)
            .header("Accept-Language", language)  // "en" or "ar"
            .GET()
            .build();

        HttpResponse<String> response = httpClient.send(
            request, 
            HttpResponse.BodyHandlers.ofString()
        );

        return response.body();
    }

    // Example usage
    public static void main(String[] args) throws Exception {
        AtlasApiClient client = new AtlasApiClient(
            "your_public_key", 
            "your_secret_key"
        );
        
        // Get countries in English
        String countries = client.getCountries("en");
        
        // Get countries in Arabic
        String countriesAr = client.getCountries("ar");
    }
}
const axios = require('axios');

class AtlasApiClient {
  constructor(publicKey, secretKey) {
    this.publicKey = publicKey;
    this.secretKey = secretKey;
    this.baseURL = 'https://atlasapi.solvytix.com/api';
  }

  async getCountries(language = 'en') {
    try {
      const response = await axios.get(`${this.baseURL}/Countries`, {
        headers: {
          'X-Public-Key': this.publicKey,
          'X-Secret-Key': this.secretKey,
          'Accept-Language': language  // 'en' for English, 'ar' for Arabic
        }
      });
      return response.data;
    } catch (error) {
      console.error('Error fetching countries:', error.message);
      throw error;
    }
  }

  async getGovernorates(countryId, language = 'en') {
    try {
      const response = await axios.get(
        `${this.baseURL}/Governorates/${countryId}`, 
        {
          headers: {
            'X-Public-Key': this.publicKey,
            'X-Secret-Key': this.secretKey,
            'Accept-Language': language
          }
        }
      );
      return response.data;
    } catch (error) {
      console.error('Error fetching governorates:', error.message);
      throw error;
    }
  }
}

// Example usage
const client = new AtlasApiClient('your_public_key', 'your_secret_key');

// Get countries in English
client.getCountries('en')
  .then(data => console.log('Countries (EN):', data))
  .catch(err => console.error(err));

// Get countries in Arabic
client.getCountries('ar')
  .then(data => console.log('Countries (AR):', data))
  .catch(err => console.error(err));

Request Access

Get started with SolvyAtlas API for free! Submit your request below, and you'll receive your Public Key and Secret Key credentials at no cost.

📋 What you'll receive:
• Public Key - Used to identify your application
• Secret Key - Used for secure authentication (keep confidential)
Free access to all API endpoints listed above
• Early adopter benefits for future updates

💡 Pricing: Currently free. Subscription fees may apply in the future, but early users will receive advance notice and special consideration.

Your access request has been submitted successfully. We'll review it and get back to you soon.