Geolocation

Opensolr Geolocation — find answers to your questions

API - Geolocate IP Addresses (geo_lookup)

Tells you where public IP addresses are: country, region, city, coordinates and time zone. One address or up to 50 in one call.

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

01 · Parameters

ipOne of the two

One address.

ipsOne of the two

Several: an array, a JSON array, or addresses separated by commas, semicolons or spaces. Up to 50; extras are left out and capped is true.

02 · Example

curl -s "https://opensolr.com/solr_manager/api/geo_lookup?email=YOUR_EMAIL&api_key=YOUR_API_KEY&ips=8.8.8.8,192.168.1.10"

03 · Answer

{
    "status": true,
    "contract_version": 1,
    "count": 2,
    "submitted": 2,
    "max_ips": 50,
    "capped": false,
    "results": {
        "8.8.8.8": {
            "found": true,
            "ip": "8.8.8.8",
            "country_code": "US",
            "country_name": "United States",
            "region": "California",
            "city": "Mountain View",
            "latitude": 37.386,
            "longitude": -122.0838,
            "timezone": "America/Los_Angeles"
        },
        "192.168.1.10": {
            "found": false,
            "msg": "ERROR_NOT_A_PUBLIC_IP"
        }
    }
}

results is keyed by each address as you sent it.

Only found and country_code are sure on a found entry. Every other field is left out when it is not known, never empty and never zero. Coordinates are left out when only the country is known.

timezone is always a real IANA name, such as Europe/Berlin, or absent.

Values shown are an example.

04 · Errors

ERROR_NO_IP_SUPPLIEDHTTP 400

No usable address in the request.

ERROR_GEO_LOOKUP_UNAVAILABLEHTTP 503

An address could not be looked up. Retry later; cache nothing from this answer.

ERROR_NOT_A_PUBLIC_IP, ERROR_GEO_NO_DATAHTTP 200

In one entry: not a public address, or nothing known about it. The other entries are answered.

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.

Each address counts once against the monthly API counter, and the call once against the per-minute and per-hour limits. It never uses the AI allowance.

05 · Related

The same answer on api.opensolr.com, next to the other lookups: ip_geo. The local time at an address: local_time.

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

Read Full Answer

API - Nearest Places for GPS Coordinates (nearby_places)

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.

Read Full Answer

API - Find Places by Name (place_search)

Finds places by name, or by the first letters someone types: coordinates, region and country of each match, best first.

Endpointhttps://opensolr.com/solr_manager/api/place_search
MethodGET or POST
Authemail and api_key of your account, as GET or POST parameters: Authentication.

01 · Parameters

qRequired

The name or its beginning, up to 80 characters.

countryOptional

A two-letter country code, to search in one country only.

limitOptional

How many places, 1 to 25. Default 10.

02 · Example

curl -s "https://opensolr.com/solr_manager/api/place_search?email=YOUR_EMAIL&api_key=YOUR_API_KEY&q=zala&country=RO&limit=3"

03 · Answer

{
    "status": true,
    "contract_version": 1,
    "q": "zala",
    "country_code": "RO",
    "count": 1,
    "places": [
        {
            "place": "Zalau",
            "country_code": "RO",
            "lat": 47.2,
            "lon": 23.05,
            "kind": "city",
            "region": "Salaj",
            "country": "Romania",
            "population": 52359
        }
    ]
}

kind is city, region, country or address.

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

Values shown are an example.

04 · Errors

ERROR_NO_QUERY_SUPPLIEDHTTP 400

q is empty.

ERROR_GEO_NO_DATAHTTP 404

No place by that name.

ERROR_GEO_LOOKUP_UNAVAILABLEHTTP 503

The place data could not be asked. 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.

It never uses the AI allowance.

05 · Related

Many addresses at once, on api.opensolr.com: address_geo. Postal codes: postal_codes.

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

Read Full Answer

Loading more articles...