Reverse Geocoding

There are two reversegeo APIs, the first one is /reversegeo this one returns the names of any geofences found in the location you pass it, as well as an address. The second reversegeo api is maps.pegasusgateway.com/reversegeo which is more up to date in terms of the addresses it returns and is capable of returning bulk addresses in multiple language formats, read below to find out.

/reversegeo

Single result

The GET request can be used to retrieve a single lat,lon result.

GET /reversegeo params

/reversegeo?lat=25.9865&lon=-80.11959&zones=true&nearby=5000

The response will show :

• zones: name of any geofence that this point is in. The geofence will be displayed depending on its property Visibility.
• location_full: address of the location. If the zone parameter is set true, then location_full include the name of the geofence.
• address: address of location.
• nearby: the API return the geofences inside in the specified radius. In the platform, the response show only the geofences that be points of interest and have circular type with radius 50m. The response list the first 15 geofences/points of interest ordered ascending by distance. This property contains:
• distance: distance from the location to the geofence/point of interest.
• id: id related to /geofences.
• name: name of the geofence.
• custom: the user can specify custom properties using the custom key in the geofence properties. This accepts any JSON object value.

{
    "zones": [
        "circle geofence"
    ],
    "location_full": "circle geofence 33009, Hollywood, Hallandale Beach, Broward County, Florida, US",
    "do_resolve_map": true,
    "nearby": [
        {
            "distance": 0,
            "id": 22528,
            "name": "circle geofence",
            "custom": {
                "foo": 1
            }
        },
        {
            "distance": 2385,
            "id": 13189,
            "name": "95 Segment above 826",
            "custom": {}
        },
        {
            "distance": 2849,
            "id": 4717,
            "name": "Mall",
            "custom": {
                "owner": "ADMIN",
                "retail": "true",
                "amount of stores": 100
            }
        }
    ],
    "address": "33009, Hollywood, Hallandale Beach, Broward County, Florida, US"
}

📘

Point of interest

The points of interest will be all geofences of type circular and with radius 50m that the user specified as a point of interest. In the modal create/edit geofence, the user can specify in the property Use as point of interest if the geofence is a point of interest or not. The property $checkpoint in the geofence will be set true or false according to the action of the user.

Multiple results

With the POST method you can pass multiple latitude, longitude pairs.

When you send multiple points you must specify a key, this will help you identify which json object corresponds to which lat, lon requested

POST /reversegeo

multiple lat lon pairs

POST /reversegeo?zones=true&nearby=5000

[
  {
    "key": "one",
    "lat": 25.78362,
    "lon": -80.293265
  },
  {
    "key": "two",
    "lat": 2.2006,
    "lon": -76.8197
  }
]

Result: 200 OK

{
    "two": {
        "zones": [
            "CAUCA"
        ],
        "location_full": "CAUCA La Sierra, Macizo, Cauca, CO",
        "do_resolve_map": true,
        "nearby": [
            {
                "distance": 0,
                "id": 4659,
                "name": "CAUCA",
                "custom": {
                    "owner": "ADMIN",
                    "type": "Polygon",
                    "collections": "167",
                    "id": 4659,
                    "visibility": "groups"
                }
            }
        ],
        "address": "La Sierra, Macizo, Cauca, CO"
    },
    "one": {
        "zones": [
            "DCT Headquarter"
        ],
        "location_full": "DCT Headquarter 33126, Miami-Dade County, Florida, US",
        "do_resolve_map": true,
        "nearby": [
            {
                "distance": 0,
                "id": 46222,
                "name": "DCT Headquarter",
                "custom": {}
            },
            {
                "distance": 28,
                "id": 7480,
                "name": "Laguna Azul",
                "custom": {
                    "visibility": "groups",
                    "collections": "465",
                    "speed_limit": 35,
                    "owner": "ADMIN",
                    "type": "Polygon",
                    "id": 7480
                }
            },
            {
                "distance": 1598,
                "id": 1750,
                "name": "Triton Of.230",
                "custom": {}
            }                    
        ],
        "address": "33126, Miami-Dade County, Florida, US"
    }
}

maps/reversegeo

The maps/reversegeo reverse geocoding API allows you to convert lat,lon coordinates into a human-readable address. The API synchronizes daily with OSM to bring the latest address information. The neat thing is this means you can edit something on OSM and see it reflected on the reversegeo API. Another notable difference is that this API does not provide the zones information like the /reversegeo one does. This api also features the posted speed limits response, allowing you to get the speed limits posted on the road of the address that it resolved.

maps API endpoint https://maps.pegasusgateway.com/reversegeo

Single result

For a single address request you can make a GET request with the following URL params

• Synth method is forced to "amia_text"

reversegeo?r=25.78362,-80.293265

{
    "errors": {},
    "results": {
        "025.78362000:-080.29327000": "5835 Blue Lagoon Drive. MIAMI-DADE COUNTY, FL 33126 US"
    }
}

reversegeo?r=25.78445,-80.29373&fmt={$speed-limit}

{
  "errors": {},
  "results": {
    "025.78445000:-080.29373000": "88"
  }
}

reversegeo?r=25.78445,-80.29373&fmt={$one-line,speed-limit}

# posted speed limit is shown in km/h
{
  "errors": {},
  "results": {
    "025.78445000:-080.29373000": [
      "Dolphin Expressway. MIAMI-DADE COUNTY, FL 33126 US",
      "88" 
    ]
  }
}

Multiple results

The POST method is used to pass single or multi line lat,lon reverse geocoding

• Authenticate header required: Any token from a valid pegasus session
• Rates: Per user, site, and global. Rate control is not based on number of POST requests but on number of locations requests for reverse-geo processing. Enforced via http 429. On 429, current returned object is pretty crude, and gives no info on when the ban is lifted, however, indication of which rate is violated is given.

Request object keys

• list: A list of lat-lon objects to resolve (max 100 per call)
  • lat-lon Object with lat lon, optional key, optional synth
• return_as: String: dict|list: Indicates how to return results. list yields to a list with the same size
  as the passe one. dict returns a dict whose keys are either the key passed on the lat-lon object, otherwise, an internally constructed key representaing the lat+lon object
• synth: Object. Controls how data results are returned/formatted. This object may be defined also per lat-lon object to override the request-wide set. This should be used when some of the lat-lon objects on list need to be synthetized different than the majority of items.

synth keys:

• method: String. Method to process:
  • 'std_text': return text. Legacy format
  • 'amia_text': return text. An fmt argument may be passed to format the result. An include_data boolean may be passed so that data objects, as well as text is returned.
  • 'reduced': Returns an useful object to play with.
  • If method is not passed, a long debug object is returned.
• 'lang': String (en|es|it|fr|... etc). When available, try to return names in this language.
• 'fmt': For amia_text method. An interpolation string to format the returned text. Some fields to pick: Interpolation: python formatter. Use !u and !l to convert upper, lower case, see combos below for examples

Address formatting options (fmt)

Combo formatting options

fmt options

{$multi-line}

137 Pilkington Avenue 
SUTTON COLDFIELD
BIRMINGHAM
B72 GB

{$one-line}

137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB

{$two-line}

137 Pilkington Avenue
SUTTON COLDFIELD, B72 BIRMINGHAM GB

{$one-line-short}

137 Pilkington Avenue. SUTTON COLDFIELD

basic "return_as": "dict"

body

{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774
    },
    {
      "lat": 52.54874,
      "lon": -1.81602
    },
    {
      "lat": 4.6702,
      "lon": -74.0541
    }
  ],
  "synth": {
    "method": "amia_text",
    "lang": "es"
  },
  "return_as": "dict"
}

response

{
  "errors": {},
  "results": {
    "025.77110000:-080.27740000": "5050 West Flagler Street. MIAMI, 33134 FL US",
    "052.54874000:-001.81602000": "137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB",
    "004.67020000:-074.05410000": "Carrera 14 85-68. CHAPINERO, BOGOTÁ CO"
  }
}

dict with custom keys

body

# POST body
{
  "list": [
    {
      "lat": 25.7711,
      "lon": -80.2774,
      "key": "mykey1"
    },
    {
      "lat": 52.54874,
      "lon": -1.81602,
      "key": "mykey2"
    },
    {
      "lat": 4.6702,
      "lon": -74.0541,
      "key": "mykey3"
    }
  ],
  "synth": {
    "method": "amia_text",
    "lang": "es"
  },
  "return_as": "dict"
}

response

{
  "errors": {},
  "results": {
    "mykey3": "Carrera 14 85-68. CHAPINERO, BOGOTÁ CO",
    "mykey2": "137 Pilkington Avenue. SUTTON COLDFIELD, B72 BIRMINGHAM GB",
    "mykey1": "5050 West Flagler Street. MIAMI, 33134 FL US"
  }
}