Services API¶

The service APIs accept data submission for geolocation stumbling as well as reporting a location based on IP addresses, cell or WiFi networks.

New client developments should use the Region, Geolocate or Geosubmit Version 2 APIs.

API Access Keys¶

You can anonymously submit data to the service without an API key via any of the submission APIs.

You must identify your client to the service using an API key when using one of the Region, Geolocate or Transfer (private) APIs.

If you want or need to specify an API key, you need to be provide it as a query argument in the request URI in the form:

https://location.services.mozilla.com/<API>?key=<API_KEY>

Each API key can be rate limited per calendar day, but the default is to allow an unlimited number of requests per day.

Errors¶

Each of the supported APIs can return specific error responses. In addition there are some general error responses.

Invalid API Key¶

If an API key was required but none or no valid key was given, the service responds with a keyInvalid message with a HTTP 400 error code:

{
    "error": {
        "errors": [{
            "domain": "usageLimits",
            "reason": "keyInvalid",
            "message": "Missing or invalid API key."
        }],
        "code": 400,
        "message": "Invalid API key"
    }
}

API Key Limit¶

API keys can optionally be rate limited. If the limit for a specific API key is exceeded, the service responds with a dailyLimitExceeded message with a HTTP 403 error code:

{
    "error": {
        "errors": [{
            "domain": "usageLimits",
            "reason": "dailyLimitExceeded",
            "message": "You have exceeded your daily limit."
        }],
        "code": 403,
        "message": "You have exceeded your daily limit."
    }
}

Parse Error¶

If the client sends a malformed request, typically sending malformed or invalid JSON, the service will respond with a parseError message with a HTTP 400 error code:

{
    "error": {
        "errors": [{
            "domain": "global",
            "reason": "parseError",
            "message": "Parse Error"
        }],
        "code": 400,
        "message": "Parse Error"
    }
}

Service Error¶

If there is a transient service side problem, the service might respond with HTTP 5xx error codes with unspecified HTTP bodies.

This might happen if part of the service is down or unreachable. If you encounter any 5xx responses, you should retry the request at a later time. As a service side problem is unlikely to be resolved immediately, you should wait a couple of minutes before retrying the request for the first time and a couple of hours later if there’s still a problem.

APIs¶

Historically the service first offered the custom Search (Deprecated) and Submit (Deprecated) APIs. Later it was decided to also implement the Geolocate API to lessen the burden on clients that want to support multiple location services. As an extension to this the Geosubmit (Deprecated) API was added to offer a consistent way to contribute back data to the service. Afterwards the Region API was added and Geosubmit Version 2 superseded its version 1 counterpart. Finally the Transfer (private) API was added.