Skip to content

Commit 290e9c9

Browse files
shirgoldbirdclaudejason-gardella-deepl
authored
add regional endpoint documentation (#241)
* add regional endpoint documentation * docs: improve regional endpoints documentation - Change access requirement callout from Info to Warning for visibility - Add Access requirements subsection in Technical specifications - Restate activation requirement to catch users who skip intro - Specify 403 error code for unauthorized access Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * Update docs/getting-started/regional-endpoints.mdx Co-authored-by: Jason Gardella <jason.gardella@deepl.com> * clarify API compatibility --------- Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com> Co-authored-by: Jason Gardella <jason.gardella@deepl.com>
1 parent 9ebcdaf commit 290e9c9

2 files changed

Lines changed: 202 additions & 0 deletions

File tree

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
"docs/getting-started/intro",
4141
"docs/getting-started/about",
4242
"docs/getting-started/auth",
43+
"docs/getting-started/regional-endpoints",
4344
"docs/getting-started/client-libraries",
4445
"docs/getting-started/managing-api-keys",
4546
"docs/getting-started/your-first-api-request",

‎docs/getting-started/regional-endpoints.mdx‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
title: "Regional API Endpoints"
3+
description: "Reference documentation for DeepL's regional API endpoints, including endpoint URLs, configuration, and technical specifications."
4+
public: false
5+
---
6+
7+
DeepL offers regional API endpoints that process and store data within specific geographic regions. Regional endpoints provide the same API functionality as the standard endpoint, with data processing occurring in data centers located in specific regions. These endpoints help organizations meet data residency and compliance requirements, and can also reduce latency for users in specific geographic regions.
8+
9+
<Warning>
10+
Regional endpoints are only available to customers who have signed a regional deployment addendum. Without a signed addendum, requests to regional endpoints will return a 403 authentication error. Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to discuss access.
11+
</Warning>
12+
13+
## Endpoint URLs
14+
15+
DeepL currently offers the following regional endpoints:
16+
17+
| **Region** | **Endpoint URL** |
18+
|------------|------------------|
19+
| **United States** | `https://api-us.deepl.com` |
20+
| **Japan** | `https://api-jp.deepl.com` |
21+
| **European Union (default)** | `https://api.deepl.com` |
22+
23+
24+
---
25+
26+
## Configuration
27+
28+
Regional endpoints are configured by specifying the endpoint URL in the API client. The standard endpoint URL (`https://api.deepl.com`) is replaced with the regional endpoint URL (`https://api-us.deepl.com` or `https://api-jp.deepl.com`).
29+
30+
<Tabs>
31+
<Tab title="cURL">
32+
33+
```bash
34+
# Standard endpoint
35+
curl -X POST 'https://api.deepl.com/v2/translate' \
36+
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
37+
--header 'Content-Type: application/json' \
38+
--data '{
39+
"text": ["Hello, world!"],
40+
"target_lang": "DE"
41+
}'
42+
43+
# US regional endpoint
44+
curl -X POST 'https://api-us.deepl.com/v2/translate' \
45+
--header 'Authorization: DeepL-Auth-Key [yourAuthKey]' \
46+
--header 'Content-Type: application/json' \
47+
--data '{
48+
"text": ["Hello, world!"],
49+
"target_lang": "DE"
50+
}'
51+
```
52+
53+
</Tab>
54+
<Tab title="Python">
55+
56+
The Python client library accepts a `server_url` parameter:
57+
58+
```python
59+
import deepl
60+
61+
# Standard endpoint
62+
translator = deepl.Translator("[yourAuthKey]")
63+
64+
# US regional endpoint
65+
translator = deepl.Translator(
66+
"[yourAuthKey]",
67+
server_url="https://api-us.deepl.com"
68+
)
69+
70+
# Usage remains identical
71+
result = translator.translate_text("Hello, world!", target_lang="DE")
72+
print(result.text)
73+
```
74+
75+
</Tab>
76+
<Tab title="Node.js">
77+
78+
The Node.js client library accepts a `serverUrl` option:
79+
80+
```javascript
81+
const deepl = require('deepl-node');
82+
83+
// Standard endpoint
84+
const translator = new deepl.Translator('[yourAuthKey]');
85+
86+
// US regional endpoint
87+
const translator = new deepl.Translator(
88+
'[yourAuthKey]',
89+
{ serverUrl: 'https://api-us.deepl.com' }
90+
);
91+
92+
// Usage remains identical
93+
(async () => {
94+
const result = await translator.translateText('Hello, world!', null, 'de');
95+
console.log(result.text);
96+
})();
97+
```
98+
99+
</Tab>
100+
<Tab title="Java">
101+
102+
The Java client library accepts a `TranslatorOptions` object with `setServerUrl()` method:
103+
104+
```java
105+
import com.deepl.api.*;
106+
107+
// Standard endpoint
108+
Translator translator = new Translator("[yourAuthKey]");
109+
110+
// US regional endpoint
111+
TranslatorOptions options = new TranslatorOptions()
112+
.setServerUrl("https://api-us.deepl.com");
113+
Translator translator = new Translator("[yourAuthKey]", options);
114+
115+
// Usage remains identical
116+
TextResult result = translator.translateText("Hello, world!", null, "de");
117+
System.out.println(result.getText());
118+
```
119+
120+
</Tab>
121+
<Tab title="C# / .NET">
122+
123+
The .NET client library accepts a `TranslatorOptions` object with `ServerUrl` property:
124+
125+
```csharp
126+
using DeepL;
127+
128+
// Standard endpoint
129+
var translator = new Translator("[yourAuthKey]");
130+
131+
// US regional endpoint
132+
var translator = new Translator(
133+
"[yourAuthKey]",
134+
new TranslatorOptions { ServerUrl = "https://api-us.deepl.com" }
135+
);
136+
137+
// Usage remains identical
138+
var result = await translator.TranslateTextAsync("Hello, world!", null, "de");
139+
Console.WriteLine(result.Text);
140+
```
141+
142+
</Tab>
143+
<Tab title="PHP">
144+
145+
The PHP client library accepts a `server_url` option in the options array:
146+
147+
```php
148+
use DeepL\Translator;
149+
150+
// Standard endpoint
151+
$translator = new Translator('[yourAuthKey]');
152+
153+
// US regional endpoint
154+
$translator = new Translator(
155+
'[yourAuthKey]',
156+
['server_url' => 'https://api-us.deepl.com']
157+
);
158+
159+
// Usage remains identical
160+
$result = $translator->translateText('Hello, world!', null, 'de');
161+
echo $result->text;
162+
```
163+
164+
</Tab>
165+
</Tabs>
166+
167+
---
168+
169+
## Technical specifications
170+
171+
### Access requirements
172+
173+
Regional endpoints require activation through a regional deployment addendum. Requests to regional endpoints without activation will return a 403 authentication error. Contact your account manager or [reach out to our sales team](https://www.deepl.com/contact-us) to activate regional endpoints for your account.
174+
175+
If your account has regional endpoint access, any API key can be used with any regional endpoint.
176+
177+
### API compatibility
178+
179+
Regional endpoints support all DeepL API functionality except:
180+
181+
- Voice API
182+
- Admin Analytics API
183+
184+
These endpoints are only available on the standard `api.deepl.com` endpoint.
185+
186+
### Glossaries and style rules
187+
188+
Glossaries and style rules are unique to each of DeepL's regional data centers and are not shared between them. Glossaries and style rules created via the API on one regional endpoint (e.g., `api-us.deepl.com`) are only accessible from that same endpoint.
189+
190+
Additionally, the DeepL web UI (at [deepl.com](https://www.deepl.com)) currently only accesses the European Union data center. Glossaries and style rules created in the UI are only accessible via the standard `api.deepl.com` endpoint, not regional endpoints like `api-us.deepl.com` or `api-jp.deepl.com`.
191+
192+
For more details, see the [Style rules documentation](/api-reference/style-rules).
193+
194+
---
195+
196+
## Related documentation
197+
198+
- [Client libraries](/docs/getting-started/client-libraries) - Language-specific client library documentation and configuration
199+
- [Authentication and access](/docs/getting-started/auth) - API authentication methods and security best practices
200+
- [Text translation](/api-reference/translate) - Text translation API reference
201+
- [Admin API](/api-reference/admin-api) - Programmatic API key management for enterprise administrators

0 commit comments

Comments
 (0)