Docs
DocsAddress Search

Address Search

The Address Search API is optimized for typeahead - it accepts partial queries and returns candidates fast enough to call on every keystroke. It's designed for address input fields, search boxes, and any UI that needs suggestions as the user types.

Address Search returns GeoJSON (features[].geometry.coordinates = [lon, lat]) - the opposite coordinate order from forward geocoding's plain JSON (lat/lon strings). Always read coordinates from geometry.coordinates, not from properties.

Endpoint

GET https://api.pickpoint.io/v2/address/search

Parameters

ParameterRequiredDescription
qYesPartial or full query string - address, place name, or postcode.
bboxNoBounding box to bias results: minLon,minLat,maxLon,maxLat. Pass the user's visible map area.
limitNoMax candidates to return (default 10).
langNoBCP 47 language tag for result names (e.g. en, de).
layerNoFilter by place type: address, venue, street, city, etc.
osm_tagNoFilter by OSM key/value (e.g. amenity:restaurant).
lat / lonNoAlternative to bbox: bias results toward a specific point.

Example request and response

curl "https://api.pickpoint.io/v2/address/search?q=Baker+St&bbox=-0.18,51.49,-0.12,51.53&limit=6" \
  -H "X-Api-Key: YOUR_KEY"
{
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-0.1575, 51.5236]
      },
      "properties": {
        "name":        "221B Baker Street",
        "street":      "Baker Street",
        "city":        "London",
        "postcode":    "NW1 6XE",
        "country":     "United Kingdom",
        "countrycode": "GB",
        "osm_type":    "N",
        "osm_id":      12345678
      }
    }
  ]
}

Address Search vs Forward Geocoding

Both endpoints accept a text query and return location results, but they're optimised for different workflows.

GET /v2/address/searchAddress Search
  • Partial queries - designed to be called on every keystroke as the user types
  • Viewport bias - pass bbox or lat/lon to surface nearby results
  • Fixed GeoJSON output - always returns a FeatureCollection; coordinates are [lon, lat]
  • Filter by type - layer=address, layer=venue, osm_tag=amenity:restaurant
Best for: autocomplete dropdowns, search inputs, address pickers
GET /v2/geocode/forwardForward Geocoding
  • Complete queries - works best with full address strings, not partial input
  • Viewport bias - viewbox + bounded=1 to restrict results to an area
  • Configurable output - supports all Nominatim-compatible formats via format=
  • Importance ranking - results sorted by a Wikipedia-derived relevance score
Best for: batch geocoding, backend normalization, one-shot lookups

Integration pattern

Two rules that matter in production: debounce to ~250 ms so you're not firing on every keystroke, and cancel in-flight requests when the query changes to avoid stale responses overwriting fresh ones.

// Minimal debounced autocomplete
const input = document.getElementById('address');
let timer;

input.addEventListener('input', () => {
  clearTimeout(timer);
  const q = input.value.trim();
  if (q.length < 2) return;

  timer = setTimeout(async () => {
    // Pass map viewport as bbox to bias results geographically
    const bbox = getMapBounds(); // e.g. "minLon,minLat,maxLon,maxLat"

    const res = await fetch(
      `https://api.pickpoint.io/v2/address/search?q=${encodeURIComponent(q)}&bbox=${bbox}&limit=6`,
      { headers: { 'X-Api-Key': PICKPOINT_KEY } }
    );
    const { features } = await res.json();

    // features[i].geometry.coordinates = [lon, lat]
    // features[i].properties.name      = display label
    renderSuggestions(features);
  }, 250);
});

Tips

  • Always pass bbox. Without a bounding box, "Baker Street" returns streets in dozens of cities. With the user's visible map area as bbox, the relevant one wins.
  • Use layer to filter. For a delivery address field, pass layer=address to skip POIs and city names.
  • Minimum query length. Don't fire requests on 1-character input - results are too noisy and you waste quota. Start at 2–3 characters.
  • Coordinate order. Coordinates come as [longitude, latitude] in GeoJSON. When passing to Leaflet use [lat, lon], when passing to MapLibre use [lon, lat] directly.
  • Never in the browser without a proxy. Route search calls through your backend to keep your API key private. See the Backend Examples.

Geocoding guideLeaflet tutorialMapLibre tutorialAPI Reference ↗