Fair usage of the Loco API
Our API is provided for private development purposes. Please don't distribute your API keys publicly, and please don't send public Internet traffic to our live endpoints.
Tip: For public access to translations, consider automatic deployment. Options include a free CDN with an open CORS policy.
Deploy static files
During development you're welcome to call the API as much as you need. You might download the latest strings every time you compile your app, or run a sync operation when you commit your source code. This is what the Export API is for.
When you deploy a live product we ask that you either host your own static files, or use our free CDN for over-the-air translation delivery.
Please ensure your application isn't hitting our API to display live content to your own users. If public Internet traffic is routed to our servers we may have to take measures which could affect your application. If you're not clear on what the API may be used for, please ask.
Protect your keys
If you need to embed your API key in a deployment script, always use a read-only key. This is less dangerous if it gets intercepted by a third party as it can't be used to perform any data-changing actions. Note that a read-only key could still expose information you don't intend to be public.
Distributing a "full access" key is almost as dangerous as giving out your password. If we see full access keys being used from multiple locations we'll have to assume it's been stolen and may have to revoke it.
Checking for changes
Please don't poll. If you need to download fresh data very regularly you can set up a Web hook to notify your system when new files are needed.
If you must fetch live data from the Export API on recurring schedule, we recommend sending cache control headers to avoid unnecessary transfer of unchanged data.
If you already have an exported file on your system, send the previous Last-Modified date in the If-Modified-Since header of your next request. If the data has not changed since your previous request you will receive a 304 Not Modified response. The same can be achieved by sending the previous ETag response in the If-None-Match request header.
Cache busting
Loco implements internal caching measures to alleviate the load on our databases when unchanged data is requested repeatedly. You should never notice this unless your account is subject to punitive caching.
If you think you're seeing stale data, please report this to us as a bug instead of trying to get around the problem with "cache busting" parameters.
Sending queries like /api/export/all.json?nocache=1651569699370 will result in 422 errors. See the notice regarding unsupported parameters.
CORS and JavaScript
We provide a free CDN as part of our range of deployment tools. This has an open CORS policy and can be used from the browser for serving JSON translations directly to your site visitors.
Our live API endpoints don't have a CORS policy. That means browsers can't make Ajax requests to pull down live translations from the Export API. You'll get a security error from the browser. Use our CDN, or deploy your own static files.
Hard limits
The Loco API currently has no per-hour, or per-IP rate limits. We ask that in lieu of quota-based limits that you use the API considerately. This will keep the service running well for everyone.
We may implement stricter limits in future, but along side this we're also developing our range of deployment tools to avoid reliance on the Export API for exposing live data.
Simultaneous requests
Notwithstanding the above, if you send parallel requests (to get more data faster) you may hit punitive limits. Making too many requests simultaneously will result in status 429 (Too many requests). The exact limits will vary according to the level of abuse we're experiencing. This measure is designed to protect us from things like DDOS attacks, so if you're in any doubt as to what you can get away with, we recommend you queue your requests synchronously in a single thread.
Punitive measures
Emergency measures are deployed when busy websites or popular apps overwhelm our service by abusing the API. Measures include cached responses and slowed response times. Depending on the nature of the traffic, this may be done at IP level, per API key or per project.
Under normal circumstances, data from the Export API will be the latest translations, pulled directly from the database. If we detect abuse for a particular API key (e.g. embedded calls from a mobile app) we may start sending cached responses. The duration of the cache will reflect the level of unauthorized traffic hitting our servers.
When responses are slowed down, you'll receive data at a reduced transfer rate. For example a maximum of 10KB per second. In these instances the response header will contain a warning message. To have the restrictions lifted, please adjust your API usage and get in contact with us.