Fair usage of the Loco API
Our API is provided for private development purposes, not for embedding in live applications. To keep the service running well for everyone, please use the API in accordance with our fair usage policy.
Please do:
- Do use the API to pull your translations into files.
- Do use the API to automate your localization workflow.
- Do use the API to build awesome development tools.
Please don't:
- Don't send public Internet traffic to our endpoints.
- Don't call the API for every page view of a production website.
- Don't embed API keys in distributed software (such a mobile apps).
- Don't poll the API aggressively to check for changes.
Deploy static files
During development you are welcome to call the API as much as you need. You may wish to 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.
However, when you deploy a live product we ask that you bundle or host your own static files. 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 will have to take measures which may 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.
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.
If you need to provide colleagues with API access or download links, it's preferable to invite them to your project instead of sharing your keys. Distributing keys around your organization will appear to our servers much the same as if the key was embedded in a live application.
Checking for changes
Please don't poll. If you need to download changes very regularly we recommend sending conditional cache headers to reduce the load on both sides:
If you already have an exported file on your system, send the previous Last-Modified date in the If-Modified-Since request header. If the data has not changed since your previous request you will receive a 304 Not Modified response. This saves both parties the work of transferring and storing redundant data. The same can be achieved by sending the previous ETag response in the If-None-Match request header.
See the W3C cache control specifications.
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.
Hard limits
The Loco API currently has no per-hour, or per-IP rate limits because so far it has not needed them. However, we do occasionally suffer from large spikes when our guidelines have not been followed. We ask that in lieu of strict rate limits that you use the API considerately. This will keep the service running well for everyone.
We will be implementing rate limiting in future, but along side that we'll be developing "deployment" APIs to help keep your software up to date with translations without relying on the Export API. See our roadmap.
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.
CORS and JavaScript
Our API end points do not have a CORS policy. That means you can't make Ajax requests from within a browser to pull down your translations. You will get a security error from the browser. This is in place to prevent abuse until there is an alternative solution for live feeds. A busy website that pulls translations live from our API can seriously degrade our service. Please deploy static files.
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.
Data from the Export API will not be stale by default. Your requests will return the latest translations directly from the database under normal circumstances. However, 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 will receive the 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.