API - Nearest Places for GPS Coordinates (nearby_places)

Geolocation

Turns GPS coordinates into the place they are in: the nearest named place, its region and country, the other places within a radius, and the street address when there is one on the spot.

Endpointhttps://opensolr.com/solr_manager/api/nearby_places
MethodGET or POST, a JSON body works too
Authemail and api_key of your account, as GET or POST parameters: Authentication.

01 · Parameters

coordsOne of the two

lat,lon in decimal degrees. Several pairs, up to 50, separated by ; or as an array, give the batch answer below.

lat, lonOne of the two

One pair as two fields.

withinOptional

The radius in km, 1 to 100. Default 25.

02 · Example

curl -s "https://opensolr.com/solr_manager/api/nearby_places?email=YOUR_EMAIL&api_key=YOUR_API_KEY&coords=48.8566,2.3522&within=10"

03 · Answer, one pair

{
    "status": true,
    "contract_version": 2,
    "coords": "48.8566,2.3522",
    "within_km": 10,
    "count": 2,
    "nearest": {
        "place": "Paris 04",
        "city": "Paris",
        "country_code": "FR",
        "distance_km": 0.4,
        "region": "Ile-de-France",
        "country": "France"
    },
    "places": [
        {
            "place": "Paris 04",
            "city": "Paris",
            "country_code": "FR",
            "distance_km": 0.4,
            "region": "Ile-de-France",
            "country": "France"
        },
        {
            "place": "Paris 01",
            "city": "Paris",
            "country_code": "FR",
            "distance_km": 1.1
        }
    ]
}

nearest is the first of places (up to 20, nearest first). city is place without a postal office number: the one to show.

Only place, city, country_code and distance_km are sure; the other fields are left out when not known.

When a street address is on the spot, address holds it: street, number, postal_code, city and more, when known.

Several pairs answer {"status": true, "contract_version": 1, "within_km": 25, "count": N, "results": {...}}, one answer like the one above per pair, keyed by the pair rounded to four decimals.

Values shown are an example.

04 · Errors

ERROR_INVALID_COORDSHTTP 400

No usable pair. 0,0 is refused too.

ERROR_GEO_NO_DATAHTTP 404

One pair: no named place within the radius. In a batch it is per pair, with 200.

ERROR_GEO_LOOKUP_UNAVAILABLEHTTP 503

A pair could not be looked up. Retry later.

ERROR_AUTHENTICATION_FAILEDHTTP 403

The email and API key do not match.

ERROR_RATE_LIMIT_PER_MINUTEHTTP 429

Too many calls. Wait for the Retry-After seconds.

A call counts once, whatever the number of pairs. It never uses the AI allowance.

05 · Related

The same lookup on api.opensolr.com, always with the batch answer: reverse_geo. The other way, a name to coordinates: place_search.

Every error code and HTTP status of the API: API errors. Calls per minute and per hour: Rate limits.