{"uid":"cap_srGVN-uKE8j8mVnbwun-c","slug":"2s-geocode-address-forward-geocoding-bdca7852","name":"2s Geocode Address (Forward Geocoding)","description":"Forward geocoding — free-text address or place name → latitude/longitude plus structured address components (houseNumber, road, suburb, city, county, state, postcode, country, countryCode). Query: q (2-500 chars), limit (1-10, default 5), country (optional 2-letter ISO 3166-1 bias). Underlying data is OpenStreetMap (ODbL). Sister: /api/geocode/reverse.","url":"https://2s.io/api/geocode/address","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method","queryParams"],"properties":{"type":{"const":"http"},"method":{"const":"GET"},"queryParams":{"type":"object","required":["q"],"properties":{"q":{"type":"string","maxLength":500,"minLength":2},"limit":{"type":"integer","default":5,"maximum":10,"minimum":1},"country":{"type":"string"}},"additionalProperties":false}}}}},"responseSchema":null,"example":{"request":{"input":{"type":"http","method":"GET","queryParams":{"q":"San Francisco California","limit":5}}},"response":{"data":{"ok":true,"meta":{"query":{"kind":"forward","input":"San Francisco California"},"cacheHit":false},"items":[{"type":"administrative","class":"boundary","address":{"city":"San Francisco","road":null,"state":"California","county":null,"suburb":null,"country":"United States of America","postcode":"94102","countryCode":"us","houseNumber":null},"latitude":37.7879363,"longitude":-122.4075201,"importance":0.780971280931417,"boundingBox":[37.6403143,37.9296678,-123.173825,-122.2814578],"formattedAddress":"San Francisco, California, USA"}],"total":null,"source":{"url":"https://www.openstreetmap.org/copyright","license":"LocationIQ terms (attribution required)","provider":"OpenStreetMap contributors"}},"meta":{"cost":{"usd":0.001,"tier":0},"caller":"x402","version":null,"endpoint":"geocode.address","settlement":{"txHash":"0xdc46c1bbb390162919113625b2340a592c2aa40498ce6b548435c78bf9180519","network":"eip155:8453","success":true}}}},"exampleRequest":{"q":"San Francisco California","limit":5},"tags":["x402"],"displayCostAmount":"0.001","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":1,"rating":{"score":"1.00","successRate":"1.00","reviews":1,"stars":"5.0","state":"rated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.001/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.0025","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.0025","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_SvXM6M5ilhnNCkeG5tdBL","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.0025","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Converts a free-text address or place name into geographic coordinates (lat/lon) and structured address components using OpenStreetMap/LocationIQ.","exampleAgentPrompt":"Can you geocode '1600 Amphitheatre Parkway, Mountain View, California' and give me its latitude, longitude, and formatted address — return the top 3 results?","exampleUseCases":null,"resultDescription":"Returns an array of matching location objects, each with latitude, longitude, formatted address string, bounding box coordinates, address components (city, state, country, postcode, house number), location type/class, and an importance score. Also includes the upstream source/license info (OpenStreetMap/LocationIQ) and metadata about whether the result was cache-hit.","failureModes":["Query string too short (< 2 chars) — returns validation error","No matching location found — returns empty items array with total null","Invalid country code format (not 2 lowercase letters) — returns validation error","Limit out of range (< 1 or > 10) — returns validation error","Payment failure via x402 — 402 response before data is returned","Upstream geocoding provider unavailable — service error response"],"whenToPreferThis":"Choose this endpoint when you need to forward-geocode a free-text address or place name into coordinates without managing API keys or monthly subscriptions. Ideal for AI agents operating on a pay-per-call basis using USDC on Base or Solana. Backed by OpenStreetMap/LocationIQ data. Prefer over raw Nominatim when you need a unified, metered, agent-friendly REST wrapper with structured JSON output.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":13,"lastUsedAt":"2026-07-28T02:19:11.103Z","lastSuccessfullyRanAt":"2026-07-28T02:19:11.103Z","lastHealthCheckAt":"2026-09-13T12:57:57.971Z","isFirstParty":false}