# French Legal Search API - LLM Integration Guide

## Quick Start

**Base URL**: `https://api.goodlegal.fr`
**Authentication**: API Key required (Bearer token or query parameter)
**Content-Type**: `application/json`

## Getting an API Key

1. Visit: `https://api.goodlegal.fr/dashboard`
2. Create account or login
3. Copy your API key from the dashboard
4. Use in requests: `Authorization: Bearer YOUR_API_KEY`

## Core Endpoints

### 1. Intelligent Search (Recommended)
**POST** `/v0/search`
- **Purpose**: Automatically routes to the best endpoint based on query
- **Use for**: Any French legal query
- **Body**: `{"query": "your search terms"}`

### 2. AI Legal Research Agent
**POST** `/v0/agent` 
- **Purpose**: Complete legal research with citations
- **Use for**: Complex legal questions requiring comprehensive analysis
- **Body**: `{"query": "your legal question"}`

### 3. Case Law Search
**POST** `/v0/case-search`
- **Purpose**: Search French jurisprudence
- **Use for**: Finding court decisions and case law
- **Body**: `{"query": "legal concept", "start_date": "2020-01-01", "end_date": "2024-12-31"}`

### 4. Legislation Search
**POST** `/v0/legislation-search`
- **Purpose**: Search French legal codes and laws
- **Use for**: Finding legal articles and regulations
- **Body**: `{"query": "legal topic"}`

### 5. Specific Case Retrieval
**POST** `/v0/case-retrieve`
- **Purpose**: Get specific court decisions by reference number
- **Use for**: Retrieving exact cases when you have jurisprudence numbers
- **Body**: `{"query": "24-86.834"}` or `{"query": "Cass. civ., 12 avril 2012, n° 11-15.000"}`

### 6. Specific Legislation Retrieval
**POST** `/v0/legislation-retrieve`
- **Purpose**: Get specific legal articles by reference
- **Use for**: Retrieving exact articles when you have precise references
- **Body**: `{"query": "article 1240 du code civil"}` or `{"query": "L313-3 CESEDA"}`

### 7. EU Law Retrieval
**POST** `/v0/eu-retrieve`
- **Purpose**: Get EU legal texts by CELEX reference
- **Use for**: Retrieving EU directives, regulations, court decisions
- **Body**: `{"query": "directive 2016/97/UE"}` or `{"query": "C-131/12"}`

### 8. Batch Legal Reference Extraction
**POST** `/v0/batch-legislation`
- **Purpose**: Extract and retrieve all legal references from multiple texts
- **Use for**: Processing documents with many legal citations
- **Body**: `{"sources": ["text with legal refs", "another text"], "comprehensive": true}`

### 9. Single Text Legal Extraction
**POST** `/v0/single-text-legislation`
- **Purpose**: Extract all legal references from one text
- **Use for**: Processing emails, documents, contracts for legal citations
- **Body**: `{"text": "your text with legal references"}`

### 10. Case-Legislation Organization
**POST** `/v0/case-legislation`
- **Purpose**: Most powerful raw search tool here. Will retrieve 35 cases and laws organized by code and article
- **Use for**: Initial search to find all relevant articles and holdings in similar cases. Gets comprehensive legal analysis with case law and legislation together
- **Body**: `{"query": "your legal topic"}`
- **Returns**: Organized structure showing:
  - Codes sorted by citation frequency
  - Articles within each code sorted by citation frequency
  - Full article content from legislation database
  - Legal principles (Portées) from cases citing each article
  - Automatic merging of top 25 all-time cases + top 10 recent cases (past 10 years)
- **Example**: Query "force majeure" returns all relevant articles from Civil Code, Commercial Code, etc., with case law showing how courts interpret each article in relation to the query.

### 11. Article Citation Search
**POST** `/v0/article-citation-search`
- **Purpose**: Search through all cases that cite a specific article ID
- **Use for**: Finding all relevant case law that references a particular legal article, filtered by search query
- **Body**: `{"article_id": "LEGIARTI000032041431", "query": "grève force majeure", "top_k": 10}`
- **Parameters:**
  - `article_id` (required): The Legifrance article ID to filter cases by
  - `query` (required): The search query to find relevant cases
  - `top_k` (optional): Number of results to return (default: 10, max: 25)
- **Response:** Returns relevant cases that cite the specified article, ranked by relevance to the search query. Each result includes the case title (generated from metadata), facts (Faits), legal principle (Portée), and source URL.

### 12. Service Public Doctrine Search
**POST** `/v0/doctrine-search`
- **Purpose**: Search Service Public administrative guidance documents
- **Use for**: Finding practical French government guidance for citizens and businesses
- **Body**: `{"query": "contrat de professionnalisation"}`
- **Returns**: Array of search results with Pinecone IDs for retrieval

### 13. Service Public Doctrine Retrieval
**POST** `/v0/doctrine-retrieve`
- **Purpose**: Get complete Service Public document by ID from search results
- **Use for**: Retrieving full text and URL of specific guidance documents
- **Body**: `{"id": "F15478-vosdroits-entreprises"}`
- **Note**: Use the full Pinecone ID from `/v0/doctrine-search` results (format: `{document_id}-vosdroits-{corpus}`)

## Response Format

All endpoints return JSON arrays with this structure:
```json
[
  {
    "snippet": "Legal text content with context",
    "uri": "https://legifrance.gouv.fr/link-to-source"
  }
]
```

## Authentication Examples

**Method 1 - Bearer Token (Recommended)**:
```bash
curl -X POST "https://api.goodlegal.fr/v0/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "responsabilité contractuelle"}'
```

**Method 2 - Query Parameter**:
```bash
curl -X POST "https://api.goodlegal.fr/v0/search?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "responsabilité contractuelle"}'
```

## Common Use Cases for LLMs

### Legal Research
```json
POST /v0/agent
{"query": "What are the conditions for acquiring French nationality by naturalization?"}
```

### Finding Relevant Case Law
```json
POST /v0/case-search
{"query": "force majeure covid-19", "start_date": "2020-01-01"}
```

### Getting Specific Legal Articles
```json
POST /v0/legislation-retrieve
{"query": "article 1240 code civil"}
```

### Processing Legal Documents
```json
POST /v0/single-text-legislation
{"text": "Selon l'article 1240 du code civil et l'arrêt de la Cour de cassation du 12 avril 2012, pourvoi n° 11-15.000..."}
```

### EU Law Research
```json
POST /v0/eu-retrieve
{"query": "directive 2016/679 RGPD"}
```

### Service Public Administrative Guidance
```json
POST /v0/doctrine-search
{"query": "allocation familiales conditions"}
```

### Retrieving Full Service Public Documents
```json
POST /v0/doctrine-retrieve
{"id": "F15478-vosdroits-particuliers"}
```

### Comprehensive Legal Analysis (Case Law + Legislation)
```json
POST /v0/case-legislation
{"query": "responsabilité contractuelle"}
```
Returns organized structure by code (Civil Code, Commercial Code, etc.) and article, with full article text and all case law citing each article.

### Finding Cases Citing a Specific Article
```json
POST /v0/article-citation-search
{"article_id": "LEGIARTI000006444136", "query": "force majeure"}
```
Returns top 25 cases that cite the specific article, ranked by relevance to the query.

## Error Handling

- **401**: Invalid or missing API key
- **400**: Invalid request format
- **500**: Server error
- **Empty array []**: No results found

## Rate Limits

- **Each API key has a request limit (default: 1000 requests)**
- **Check your usage in the dashboard**
- **Contact admin for limit increases**

## Best Practices for LLMs

1. **Start with `/v0/search`** - it automatically chooses the best endpoint
2. **Use `/v0/agent`** for complex research requiring multiple sources
3. **Be specific** - include article numbers, case references, dates when known
4. **Handle empty results** - not all queries will return results
5. **Always include authentication** - all endpoints require API keys
6. **Check URIs** - use the provided links for source verification

## Language Support

- **Input**: French legal terms work best, but English is accepted
- **Output**: Results are in French (original legal language)
- **Scope**: French law, EU law affecting France, some comparative law

## System Capabilities

- **Real-time access** to Legifrance database
- **Semantic search** using OpenAI embeddings
- **Exact reference matching** for precise citations
- **Historical article versions** when available
- **Comprehensive case summaries** with structured metadata
- **Automatic legal reference extraction** from text

## Quick Implementation Template

```python
import requests

def query_french_law(query, endpoint="search", api_key="YOUR_API_KEY"):
    url = f"https://api.goodlegal.fr/v0/{endpoint}"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    data = {"query": query}

    response = requests.post(url, headers=headers, json=data)
    if response.status_code == 200:
        return response.json()
    else:
        return {"error": response.status_code, "message": response.text}

# Example usage
results = query_french_law("article 1240 code civil")
for result in results:
    print(f"Content: {result['snippet']}")
    print(f"Source: {result['uri']}")
```

## Gemini 2.5 Flash Integration

This API is specifically designed for Gemini grounding. Configure as external API tool:

```json
{
  "tools": [{
    "retrieval": {
      "externalApi": {
        "api_spec": "SIMPLE_SEARCH",
        "endpoint": "https://api.goodlegal.fr/v0/search",
        "apiAuth": {
          "apiKeyConfig": {
            "apiKeyString": "YOUR_API_KEY"
          }
        }
      }
    }
  }]
}
```

## Support

- **Dashboard**: `https://api.goodlegal.fr/dashboard`
- **API Docs**: `https://api.goodlegal.fr/docs`
- **Health Check**: `https://api.goodlegal.fr/health`

---

**Ready to use**: Get your API key from the dashboard at `https://api.goodlegal.fr/dashboard` to start making requests immediately.