Forward geocoding – search locations by name or address

GET /nominatim/search

Search for locations by name, address, or place using OpenStreetMap Nominatim. Returns coordinates and details for matching locations. Worldwide coverage. The endpoint is a pass-through to the upstream Nominatim instance, so any Nominatim parameter (e.g. viewbox, bounded, extratags, namedetails, polygon_geojson) is forwarded as-is; only the parameters most relevant to typical use are documented here.

Parameters

Parameter	Type	Required	Description	Example
`q`	string	✓	Search query (free-form address or place name)	`London Eye`
`format`	string		Output format Values: json, jsonv2, xml, geojson, geocodejson Default: jsonv2	`jsonv2`
`limit`	integer		Maximum number of results to return Default: 10	`5`
`addressdetails`	integer		Include detailed address breakdown (0 or 1) Values: 0, 1 Default: 0	`1`
`countrycodes`	string		Comma-separated ISO 3166-1alpha2 country codes to limit search	`gb,us`
`accept-language`	string		Preferred language for results (ISO 639-1 codes)	`en`

Try It Out

Base URL: https://capi.busmaps.com:8443

Example Requests:

Required parameters only

curl -H "capi-key: Bearer YOUR_API_KEY" \
     -H "capi-host: busmaps.com" \
     "https://capi.busmaps.com:8443/nominatim/search?q=London Eye"

Common usage with optional parameters

curl -H "capi-key: Bearer YOUR_API_KEY" \
     -H "capi-host: busmaps.com" \
     "https://capi.busmaps.com:8443/nominatim/search?q=London Eye&limit=5"

Popular parameters

curl -H "capi-key: Bearer YOUR_API_KEY" \
     -H "capi-host: busmaps.com" \
     "https://capi.busmaps.com:8443/nominatim/search?q=London Eye&format=jsonv2&limit=5&addressdetails=1&countrycodes=gb,us&accept-language=en"

Response Example

HTTP 200 - Success

[
  {
    "address": {
      "ISO3166-2-lvl4": "GB-ENG",
      "ISO3166-2-lvl8": "GB-LBH",
      "city": "London",
      "city_district": "London Borough of Lambeth",
      "country": "United Kingdom",
      "country_code": "gb",
      "postcode": "SE1 7PB",
      "quarter": "South Bank",
      "road": "Westminster Bridge Road",
      "state": "England",
      "state_district": "Greater London",
      "suburb": "Lambeth",
      "tourism": "London Eye"
    },
    "addresstype": "tourism",
    "boundingbox": [
      "51.5027354",
      "51.5039478",
      "-0.1198608",
      "-0.1194922"
    ],
    "category": "tourism",
    "display_name": "London Eye, Westminster Bridge Road, South Bank, Lambeth, London Borough of Lambeth, London, Greater London, England, SE1 7PB, United Kingdom",
    "importance": 9.99999999995449e-06,
    "lat": "51.5033416",
    "lon": "-0.11967649999999999",
    "name": "London Eye",
    "osm_id": 204068874,
    "osm_type": "way",
    "place_id": 275272080,
    "place_rank": 30,
    "type": "attraction"
  },
  {
    "address": {
      "ISO3166-2-lvl6": "AL-10",
      "amenity": "London Eye",
      "city": "Shkodër",
      "country": "Shqipëria",
      "country_code": "al",
      "county": "Qarku i Shkodrës",
      "house_number": "6",
      "municipality": "Bashkia Shkodër",
      "postcode": "4001",
      "quarter": "Vasil Shanto",
      "road": "Rruga Dr. Selaudin Bekteshi",
      "state": "Shqipëria Veriore",
      "suburb": "Lagjja 3"
    },
    "addresstype": "amenity",
    "boundingbox": [
      "42.0685708",
      "42.0686708",
      "19.5142695",
      "19.5143695"
    ],
    "category": "amenity",
    "display_name": "London Eye, 6, Rruga Dr. Selaudin Bekteshi, Vasil Shanto, Lagjja 3, Shkodër, Bashkia Shkodër, Qarku i Shkodrës, Shqipëria Veriore, 4001, Shqipëria",
    "importance": 9.99999999995449e-06,
    "lat": "42.0686208",
    "lon": "19.5143195",
    "name": "London Eye",
    "osm_id": 3877861155,
    "osm_type": "node",
    "place_id": 55383262,
    "place_rank": 30,
    "type": "bar"
  }
]

Response Schema

Title: Nominatim Forward Geocoding Response

View Full JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Nominatim Forward Geocoding Response",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "address": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City"
          },
          "amenity": {
            "type": "string",
            "description": "Amenity name/type at the location"
          },
          "state": {
            "type": "string",
            "description": "State/region"
          },
          "postcode": {
            "type": "string",
            "description": "Postal code"
          },
          "municipality": {
            "type": "string",
            "description": "Municipality"
          },
          "highway": {
            "type": "string",
            "description": "Highway feature at the location"
          },
          "country": {
            "type": "string",
            "description": "Country name"
          },
          "ISO3166-2-lvl4": {
            "type": "string",
            "description": "ISO 3166-2 subdivision code (level 4)"
          },
          "road": {
            "type": "string",
            "description": "Street/road name"
          },
          "city_district": {
            "type": "string",
            "description": "City district"
          },
          "tourism": {
            "type": "string",
            "description": "Tourism feature at the location"
          },
          "country_code": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code"
          },
          "ISO3166-2-lvl8": {
            "type": "string",
            "description": "ISO 3166-2 subdivision code (level 8)"
          },
          "state_district": {
            "type": "string",
            "description": "State district"
          },
          "suburb": {
            "type": "string",
            "description": "Suburb"
          },
          "quarter": {
            "type": "string",
            "description": "Quarter"
          },
          "county": {
            "type": "string",
            "description": "County"
          },
          "house_number": {
            "type": "string",
            "description": "House number"
          },
          "ISO3166-2-lvl6": {
            "type": "string",
            "description": "ISO 3166-2 subdivision code (level 6)"
          }
        },
        "required": [
          "city",
          "road",
          "state",
          "postcode",
          "country_code",
          "suburb",
          "quarter",
          "country"
        ],
        "description": "Address components breakdown (if addressdetails=1)"
      },
      "osm_type": {
        "type": "string",
        "description": "OpenStreetMap element type (node, way, relation)"
      },
      "importance": {
        "type": "number",
        "description": "Search result importance score"
      },
      "addresstype": {
        "type": "string",
        "description": "Type of address component returned"
      },
      "name": {
        "type": "string",
        "description": "Display name"
      },
      "boundingbox": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Bounding box coordinates [minlat, maxlat, minlon, maxlon]"
      },
      "type": {
        "type": "string",
        "description": "Type discriminator for the object"
      },
      "place_id": {
        "type": "integer",
        "description": "Unique identifier for the place in OSM Nominatim"
      },
      "lon": {
        "type": "string",
        "description": "Longitude in decimal degrees"
      },
      "osm_id": {
        "type": "integer",
        "description": "OpenStreetMap element ID"
      },
      "lat": {
        "type": "string",
        "description": "Latitude in decimal degrees"
      },
      "place_rank": {
        "type": "integer",
        "description": "Nominatim importance rank of the place"
      },
      "category": {
        "type": "string",
        "description": "OSM category/class (highway, building, amenity, tourism, etc.)"
      },
      "display_name": {
        "type": "string",
        "description": "Full human-readable address"
      }
    },
    "required": [
      "type",
      "osm_type",
      "place_id",
      "importance",
      "category",
      "lon",
      "osm_id",
      "addresstype",
      "lat",
      "display_name",
      "place_rank",
      "name",
      "boundingbox"
    ]
  }
}

Response Codes

HTTP 200

Search completed successfully (may return empty array if no results)

HTTP 400

Invalid search parameters

HTTP 500

Internal server error