Services and field tools

Search and addresses

Find places and turn map coordinates into nearby addresses using the service client or plain HTTP.

On this page

Search for a place #

Prerequisites: a search-scoped key, reachable services, and either the hosted service module or the core npm package. No map or DOM is needed.

javascript

import { configure, search, reverse } from 'https://maps.example/sw-services.js';
configure({ baseUrl: 'https://maps.example/', apiKey: 'YOUR_API_KEY' });
const result = await search('Lahug, Cebu City', {
  limit: 5, near: [123.9, 10.3], lang: 'en'
});
for (const place of result.features) {
  console.log(place.properties.label, place.geometry.coordinates);
}
const address = await reverse([123.8985, 10.3326], { limit: 1 });
console.log(address.features[0]?.properties.label ?? 'No nearby address');

Expected result: a GeoJSON FeatureCollection, best matches first. near biases ranking; it is not a distance filter. Search supports barangays, streets, addresses, landmarks and other indexed OSM places, including English and Tagalog names where present.

bash

curl --fail-with-body -G https://maps.example/search   -H "X-API-Key: YOUR_API_KEY"   --data-urlencode "q=Lahug, Cebu City" --data-urlencode "limit=5"
curl --fail-with-body   -H "X-API-Key: YOUR_API_KEY"   "https://maps.example/search/reverse?at=123.8985,10.3326&limit=1"

Understand result fields #

Field	Meaning
geometry.coordinates	Longitude/latitude of the matching feature
properties.name / label	Display name and composed one-line address
properties.kind / category	Photon place type and OSM key=value category, when available
properties.address	Optional housenumber, street, locality, district, city, county, state, postcode, country and countrycode
properties.osm	Source identity such as node/123 or relation/123
bbox	Optional [west,south,east,north] extent
properties.distance_m	Reverse result distance from the query point

Address fields retain the source names: locality/district may hold a barangay, while county may hold a province or Metro Manila district. Do not rename fields based on an assumed administrative level. Handle absent fields and an empty features array. Reverse geocoding returns a nearby indexed object, not a cadastral or legal address.

Limits and failure handling #

q must be non-empty and at most 200 characters. Search limit is 1–20, default 10; reverse limit is 1–10, default 1.
near and reverse at use the service coverage envelope. lang is passed to Photon; availability depends on the indexed data.
Use AbortController to cancel stale searches and debounce text inputs. Do not let a slower old request overwrite a newer result.
400 indicates malformed parameters; 422 indicates outside coverage; 502/504 indicate engine failure/timeout. No matches can still be a successful 200 response.

javascript

const controller = new AbortController();
try {
  const found = await search('Manila', { signal: controller.signal });
  console.log(found.features.length);
} catch (error) {
  if (error.name !== 'AbortError') console.error(error.status, error.code, error.message);
}
// Cancel when your input changes or component unmounts: controller.abort();

Full search and reverse require the running services. For disconnected place-name matching, use places.json; it is a smaller point-name dataset, not an offline Photon index.