FEROEG REVERSE GEOCODING API DOCUMENTATION - March 2022 - V 0.2

The Feroeg reverse geocoding API is based on HTTP protocol.
A single point can be requested using the HTTP GET method.
Multiple points can be resolved using the batch mode: HTTP POST method.
An example of a basic request is the next one:

BASIC QUERY EXAMPLE:

https://www.feroeg.com/address?lat=45.517068&lon=9.118373
Is structured as: 
<scheme>://<domain>:<port>/address?lat=<latitude>&lon=<longitude>[&lang=<2 letters code>]
BASIC URL SCHEME:
<scheme>://<domain>:<port> can be:
http://www.feroeg.com:8080
https://www.feroeg.com
LATITUDE/LONGITUDE:
The "lat" parameter specifies the latitude (y) of the point to be geocoded.
The "lon" parameter specifies the longitude (x) of the point to be geocoded.
The parameters must be in the WGS84 format - the standard for a GPS point.

OPTIONAL PARAMETERS:

"LANG"
The "lang" parameter is optional. It will display (if available) the name of the geographical area translated in the specified language. To use it specify a language, encoded using the ISO 639-1 alpha 2 table (https://www.loc.gov/standards/iso639-2/php/code_list.php.) We suggest specifing the language used in your app, as lang=en

"FORMAT"
The "format" parameter define how the geocoder format the query, so you can get a custom formatted output.
The string used as parameter specify the list of arguments to be printed. The arguments are enclosed in square brackets.
The text outside the brackets is printed 'as is'.
If not specified, the default format schema used in a query is: format='[SN[, ] - [23456789ab[, ]'
The text enclosed in brackets define the arguments, a optional text prefix and an optional text separator ([parameters[prefix[separator]).

List of arguments (they are printed if found):

S = Print the street name
N = Print the street number
2..b = Print the corresponding administrative level (2=nation and so on)
X,Y = X (longitude) and Y (latitude) shows the coordinates present in the query.
x,y = 'x' and 'y' representing interpolated coordinates projected to the nearest Street.
d = Distance (mt) from the street of query point.

Special arguments:

R = Disable admin name redundancy as repeating the same name (must be first letter in the bracket)
F = 'Fast Mode' - switch: (must be at the First letter of the schema) for resolve and get only the nearest way. Using this switch the query is also a bit faster because the part about resolving address house numbers is not executed.
Use it if you want only the administrative names or you want the (x,y) interpolating coordinated.


"KEY"
The "key" parameter is optional. In the future will be mandatory, especially to enable special features or for the payment version of the service. At the moment no restrictions are applied to the query. We recommend including it anyway using "key=freeplan".

MODE=text
Added mode=text query option for outputting the result in text mode (only the JSON "Result.Address" field see below)
Example :"Via Cristina Belgioioso, 2 - Italia, Lombardia, Milano, Municipio 8"

HTTP - JSON - RESPONSE OF THE QUERY :

Below is the HTTP response, encoded in JSON format, of the query reported as example: 
{ "Query": { "lat": 45.517068, "lon": 9.118373 },
  "AdminAreas": [ "Italia(2)", "Lombardia(4)", "Milano(6)", "Milano(8)", "Municipio 8(10)" ],
  "Nearest": { "InterpolatedCoords": { "lat": 45.517122, "lon": 9.118418, "dist": 7 },
               "Address": "( motorway_link ) - Italia, Lombardia, Milano, Municipio 8",
			   "OSM_StreetWayId": 589905164,
			   "OSM_AdminAreaRelId": 3953733
             },
  "Result":  { "InterpolatedCoords": { "lat": 45.517966, "lon": 9.118767, "dist": 215 },
               "Address": "Via Cristina Belgioioso, 2 - Italia, Lombardia, Milano, Municipio 8",
			   "OSM_AddressWayId": 57402975, 
			   "OSM_AddressNodeId": 94438279864320,
			   "OSM_StreetWayId": 139906616116984,
			   "OSM_AdminAreaRelId": 3953733 
             } 
}

The response comes with 4 main JSON fields:

QUERY field
The "Query" field contain the coordinates of the submitted request.

ADMINAREAS field
The "AdminAreas" lists the name of the administrative areas (and the level) corresponding to the query. The meaning of the administrative level code may vary nation by nation (for details pls see: https://wiki.openstreetmap.org/wiki/Key:admin_level).

NEAREST and RESULT fields
The "Nearest" and the "Result" fields are very similar.
The "Nearest" field contains the geocoding of the very near street, but the address is not fully qualified so it not have a specific street name and/or a street number.
The "Result" field contains the best-qualified address the service can resolve.
The latest condition is exampled in the query where to point to geocode is near to an unnamed street ( motorway link ), but is also near to another street of which we can resolve the name and the number.
Here is a description of the subfields:
The "InterpolatedCoords" subfield contains the coordinate, and the distance of the point, projected to the street.
The "Address" subfield contains the reverse geocoded address, in text format, so you can use it to get the information you required.
The "OSM_StreetWayId" subfield is the numeric id of the OpenStreetMap way element used by the service to reverse geocode the coordinate (you can query and verify it directly to OSM https://www.openstreetmap.org/way/[id] )
The "OSM_AdminAreaRelId" subfield is the numeric id of the OpenStreetMap relation used to reverse geocode the coordinate (you can query and verify it directly to OSM https://www.openstreetmap.org/relation/[id] )
The "OSM_AddressNodeId" and "OSM_StreetWayId" similarly represent other OSM elements, at the moment they are broken (after the integration with the OpenAddresses), do not use them. They will be fixed.


ABOUT JSON RESPONSE AND PRESENCE OF THE FIELDS:

The presence of the fields "Query", "AdminAreas", "Nearest", "Result" depends on some factors:
- No field is presented at all for the query which coordinates laying in an area not belonging to a nation (example: ocean, sea)
- Only "Query" and "AdminAreas" fields for queries in areas far from streets (about 200 mt)
- The "Nearest" field are not present when the "Result" field is present and the content is the same (or very similar).
- "Nearest" and "Result" field is present when the service find a fully qualified address (street name, street number) distant from the "Nearest" address, which is not fully qualified, but most accurate, in terms of geographical distance from the "Query" coordinates.
Which field, and subfield to use depend on your uses case:
For example, if you are displaying the path of a vehicle which has a GPS device onboard we suggest using the "Nearest.InterpolatedCoords" subfield or "Result.InterpolatedCoords" (if present) to fix the vehicle position on the street.
If you want to give a textual indication where the point is probably prefer to get the "Result.Address" subfield, because is typically a fully qualified address with also the street number.

EXAMPLES OF USES THE 'FORMAT' PARAMETER:

Print only the nation and the city:

It uses also X (longitude) and Y (latitude) field to show the query coordinates.
Query: https://www.feroeg.com/address?lat=40.710204&lon=-74.010544&format="FLatitude [Y] and Longitude [X] is in [52[,]]"&mode=text
Result: Latitude 40.710204 and Longitude -74.010544 is in New York,United States"

'x' and 'y' representing interpolated coordinates projected to the nearest Street:

Query: https://www.feroeg.com/address?lat=40.710204&lon=-74.010544&format=Latitude [y] and Longitude [x] are the coordinate projected to [SN[, ]. They are distant [d] meters from the query coordinates.&mode=text
Result: --- Latitude 40.710104 and Longitude -74.010625 are the coordinate projected to Cortlandt Street, 22. They are distant 13.296526 meters from the query coordinates.

BATCH MODE - HTTPS POST METHOD
Post a text file containing a pair of coordinates for each line. Output returns the same text file with the addresses appended to the end.
All params, excepted lat / lon are in the URI of the request.
The body contains the requests, organized in text row. Each row contains the lat/lon pair.
EXAMPLE:
-->HTTP Post --> https://www.feroeg.com/batch?format="F[SN[, ] - [23456789ab[, ]
---HTTP Body
40.71020 -74.010544\n
40.72020 -74.110544\n
40.73020 -74.210544\n
40.74020 -74.310544\n


THE FREE FEROEG REVERSE GEOCODING SERVICE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SERVICE OR THE USE OR OTHER DEALINGS CONCERNING THE SERVICE.